From 04b47d149b43969e6353a3f49500e35fbe43cbe1 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Mon, 8 Nov 2021 10:48:11 -0700 Subject: [PATCH] InfluxDB 2.1 (#3367) * base changes for influxdb 2.1 * remove duplicates in draft * draft categories * add categories * Document wildcards in SHOW MEASUREMENTS ON queries (#3273) * InfluxQL: document wildcards in SHOW MEASUREMENTS ON queries This applies to InfluxDB 2.1. See #3201 * latest notes * Update `influxd --store` values (#3272) * Use Unix ~ alias * Add sqlite path to file layout doc * add sqlite to filesystem diagrams * draft 2.1 release notes +questions * revert to check RNs changes in separately * latest release notes * Restructure installation docs for separate CLI package (#3280) * influxdb and cli install revamp * reorganized CLI install instructions * remove unnecessary short-code parameters * updated docs to address PR feedback * Apply suggestions from code review Co-authored-by: pierwill <19642016+pierwill@users.noreply.github.com> Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Apply suggestions from code review * update linux install instructions Co-authored-by: pierwill <19642016+pierwill@users.noreply.github.com> Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * release note updates * updates * add support for annotations in OSS 2.1 (#3286) * Document support for bearer auth sytax (#3297) * 2.1 oss notebooks (#3281) * Move notebooks to OSS (addresses #2951 ) * Update content/influxdb/v2.1/notebooks/clean-data.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/notebooks/manage-notebooks.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/notebooks/overview.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/notebooks/_index.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/notebooks/troubleshoot-notebooks.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/notebooks/clean-data.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/notebooks/clean-data.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/notebooks/clean-data.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/overview.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/overview.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/overview.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/overview.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/overview.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/overview.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/overview.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/influxdb/v2.1/notebooks/create-notebook.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Add PR feedback Co-authored-by: Scott Anderson Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Fix link in bearer auth sytax doc (#3298) * Updated CLI docs content and added version metadata (#3285) * added metadata styles and data to cli docs * added missing ui-disabled influxd config flag * added updated versions to influx cli metadata * added metadata to all cloud influx cli docs * updated influx ping in cloud to have oss only tag * Update influxd documentation for 2.1 (#3302) * update and dynamically generate links to influxd flags (#3288) * remove 2.1 config options from 2.0 * New influxd commands (#3291) * added basic influxd recovery commands * added influxd recover commands, WIP for other influxd inspect commands * updated all influxd inspect commands * Apply suggestions from code review Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * updated influxd docs to address PR feedback Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Add static legend to band and graph visualizations (#3315) * update band vis to include static legend * upd graph and graph-single-stat w static legend * update 2.1 links * update to latest Flux links * fix Flux links * Influxdb 2.1 release notes (#3279) * draft release notes * latest RN changes * test * revert * for review purposes * incorporate changes from new changelog * add note about new metadata included in CLI docs * edit * more edits * add overview features list * tweak verbiage about Telegraf support * Update content/influxdb/v2.1/reference/release-notes/influxdb.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/reference/release-notes/influxdb.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/reference/release-notes/influxdb.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/reference/release-notes/influxdb.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/reference/release-notes/influxdb.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/reference/release-notes/influxdb.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/reference/release-notes/influxdb.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/reference/release-notes/influxdb.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/reference/release-notes/influxdb.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/reference/release-notes/influxdb.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.1/reference/release-notes/influxdb.md Co-authored-by: Scott Anderson * add link * add edits from Scott, Dan, and Will * edits from dan * highlight and distinguish CLI separation changes * add links to new API endpoints * formatting upd * edits for secrets * mv Flux location support after rsv merge conflicts * edits from Tim * update influxql link * rmv SLQ metastore link * minor updates to 2.1 release notes * prep * Update content/influxdb/v2.1/reference/release-notes/influxdb.md Co-authored-by: Greg <2653109+glinton@users.noreply.github.com> Co-authored-by: Scott Anderson Co-authored-by: Scott Anderson Co-authored-by: Greg <2653109+glinton@users.noreply.github.com> * add new Telegraf plugins to release notes * edit from Will * 2.1 upgrade and downgrade instructions (#3332) * influxd downgrade command, add upgrade instructions, closes #3331 * Apply suggestions from code review Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Daniel Moran * udpated downgrade docs to address PR feedback * remove references to localhost:1313 Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> Co-authored-by: Daniel Moran * updated flux version in release notes, added other new items, closes #3338 (#3344) * Chore/update oss api (#3341) * Standardize the term "key-value" (#3283) * s|key/value|key-value * Use en dash in prefix to open compound "time series" * CLI 2.2 (#3269) * add -b shorthand to influx delete * add cli 2.2 release notes * add example for all-access token * edits * updates to influx auth create * edits for operator token * remove inaccurate env var * Update influx-cli.md * Update influx-cli.md * make capitalization consistent with other docs * make headers parallel * Update content/influxdb/cloud/reference/release-notes/influx-cli.md Co-authored-by: Scott Anderson * Update content/influxdb/cloud/reference/release-notes/influx-cli.md Co-authored-by: Scott Anderson * Update content/influxdb/cloud/reference/release-notes/influx-cli.md Co-authored-by: Scott Anderson * edits from Scott and Dan * Update content/influxdb/v2.0/reference/cli/influx/auth/create.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.0/reference/cli/influx/auth/create.md Co-authored-by: Daniel Moran * Update content/influxdb/v2.0/reference/cli/influx/auth/create.md Co-authored-by: Daniel Moran * edits to CLI * add oss-only shortcode and fix formatting * format updates * fix links * add oss-only inline * fix list * Update content/influxdb/v2.0/security/tokens/create-token.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.0/security/tokens/create-token.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.0/security/tokens/create-token.md Co-authored-by: Scott Anderson * edits from Dan * emphasize recommendation * edit from Dan re limits and page size * edit f Sam * update release date * remove vague description * Update content/influxdb/cloud/reference/release-notes/influx-cli.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.0/reference/cli/influx/auth/create.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.0/reference/cli/influx/auth/create.md Co-authored-by: Scott Anderson * Update content/influxdb/cloud/reference/release-notes/influx-cli.md Co-authored-by: Scott Anderson * Update content/influxdb/cloud/reference/release-notes/influx-cli.md Co-authored-by: Scott Anderson * edits from Scott Co-authored-by: Scott Anderson Co-authored-by: Daniel Moran * add cloud updates in Sept (#3210) * Fix numbering in AWS install doc (#3293) Closes #3292 * Document new API Invocable Scripts feature (was named-functions) (#3282) * feat: add api-guides/guides and guides/api-invocable-scripts for the API-invocable scripts (managed functions) feature (##2547, #2233). * feat: document API-invocable scripts. Add example for creating and invoking a script with POST. Unable to make GET work with query parameters. * feat: moved API-invocable scripts under api-guide. Remove guides directory. Add docs for list and find. Add example for list. Add shortcuts and glossary links. Verified with team-compute that GET /invoke and python are not supported yet. * feat: rename example function for simplicity since there's no GET for now. * feat: add find_and_update example (#2547). * feat: add update example. Clarify, expand invoke example. Add links. (#2547) * Update content/influxdb/cloud/api-guide/api-invocable-scripts/_index.md Co-authored-by: Scott Anderson * fix: remove accidental commit of generated redoc-static.html * feat: manual update to cloud swagger. Merges meta, auth, tags, and x-tagGroups from src/cloud.yml to aggregate contracts/ref/cloud.yml. * fix: replace /functions with /scripts * feat: get swaggers from contracts/ref. Still requires copy-paste of info, tags, and auth from contracts/cloud.yml and contracts/oss.yml * feat: invocable scripts (#2547) * Update content/influxdb/cloud/api-guide/api-invocable-scripts/_index.md Co-authored-by: pierwill <19642016+pierwill@users.noreply.github.com> * feat: new section for params (#2547). * fix: swagger server url (#2547) * Update content/influxdb/cloud/api-guide/api-invocable-scripts/_index.md Co-authored-by: Scott Anderson * feat: remove jq and function where there's no clear need. Co-authored-by: pierwill <19642016+pierwill@users.noreply.github.com> * fix: add Invocable Scripts tag description. (#3296) * Fix api invocable (#3299) * fix: scripts api path. * fix: bad comma * Fix api invocable (#3306) * fix: scripts api path. * fix: bad comma * feat: add invocable scripts example for sending multiple parameter values. * fix: endpoint text. (#3308) * Fix api invocable (#3310) * fix: measurement -> point * fix: cloud API ref. Remove private paths. Patch description and orgID params into ScriptCreateRequest. * updated token naming and other typos, closes influxdata/DAR#244 (#3309) * Flux 0.136 (#3311) * Flux 0.136.0 release notes * Update pagerduty package for flux 0.136.0 (#3303) * Add Flux ServiceNow package (#3304) * added Flux servicenow package * Apply suggestions from code review * Enterprise dar updates (#3313) * removed references to web server in enteprise cluster docs, closes influxdata/DAR#245 * updated enterprise upgrade instructions, closes influxdata/DAR#243 * Apply suggestions from code review Co-authored-by: pierwill <19642016+pierwill@users.noreply.github.com> Co-authored-by: pierwill <19642016+pierwill@users.noreply.github.com> * fix: mjs example path (#3305) (#3316) * 3240 fix nodejs alias (#3317) * fix: mjs example path (#3305) * fix: add alias to node.js client library (#3240) * Edit description for amd_rocm_smi Telegraf plugin (#3186) * Edit description for amd_rocm_smi Telegraf plugin Edit name and description for amd_rocm_smi Telegraf plugin. Not sure if this is the only location that it needs to be udpated. * cpl minor updates Co-authored-by: Kelly * remove influxql support from v2 api, closes influxdata/DAR#246 (#3326) * Telegraf 1.20.3 (#3328) * Telegraf 1.20.3 * Update content/telegraf/v1.20/about_the_project/release-notes-changelog.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/telegraf/v1.20/about_the_project/release-notes-changelog.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Update content/telegraf/v1.20/about_the_project/release-notes-changelog.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Address PR feedback Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * docs: update telegraf configuration.md (#3300) * docs: update telegraf configuration.md * add note about rate limits * fix: correct debian/ubuntu install instructions (#3312) * fix: correct debian/ubuntu install instructions This consolidates the Debian and Ubutnu install instructions into one section. The install instructions can be the same for both as they use the same package manager (i.e. apt). This removes the use of the now deprecated pipe to apt-key. This removes references to starting the service, as the service starts on install and does not require an extra step. Also all supported operating systems are using systemd at this point so no need to call that out seperatly. Removes an extra 'sudo' in deb instructions. * missing word * added flux 0.137.0 release notes, added vertica sql support docs (#3318) * Update _index.md (#3195) broken link for external plugin repo * Addresses #3284 (#3334) * Updates to Flux `to()` (#3260) Closes https://github.com/influxdata/DAR/issues/236. Closes #3258. Co-authored-by: Scott Anderson * Fix shim and other link (#3336) * Update Kapacitor security docs (#3325) Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Include TLS setup in Enterprise post-install steps (#3271) - Rename TLS guide file. - Use term "TLS" in title and introduction of TLS guide. Closes #3270. Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Flux 0.138.0 and 0.139.0 (#3335) * added release notes for flux 0.138 and 0.139 and related updates * updated spec with related implementation issue * Apply suggestions from code review Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * updated to address PR feedback, added related links to int, uint, and bitwise docs Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * hotfix load data link * add aliases and fix load data link in oss * API Ref docs processing (#3337) * chore: API Reference Docs custom processing. Pulls contracts/ref files and applies custom content (tags, x-tagGroups, securitySchemes, info) before writing results to cloud/ref.yml and v2.0/ref.yml. Rename source files from swagger.yml to ref.yml to avoid confusion and in case we need to bundle additional specs in the future. Add an OpenAPI CLI docs-plugin with content and decorators. * chore: update api-docs/README.md * fix: add strip-version-prefix to remove /api/v2 added incorrectly to some paths during contract generation - also fixed in openapi repo so future contracts won't need this decorator. Fix server urls. Cleanup. * chore: update cloud contract. * chore: update oss API contract. * Apply suggestions from code review Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: pierwill <19642016+pierwill@users.noreply.github.com> Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> Co-authored-by: Scott Anderson Co-authored-by: Daniel Moran Co-authored-by: Samantha Wang <32681364+sjwang90@users.noreply.github.com> Co-authored-by: Kelly Co-authored-by: noramullen1 <42354779+noramullen1@users.noreply.github.com> Co-authored-by: Joshua Powers Co-authored-by: bgilmore-iot <85192039+bgilmore-iot@users.noreply.github.com> * edit from Tim: update v2.0 to v2.1 in API section * fix 2.1 links * Fix/api ref 2.1 (#3363) * fix: cloud-specific v1compat auth examples. * fix: openapi. Disabled securityScheme replacement. Cleaned up placeholders. Added links. * fix: update API auth descriptions. add API ref v2.1. Update links in openapi content. * fix: updates URLs to v2.1 in API ref docs * add verify-tsm to 2.1 release notes * Clockface updates for 2.1 and Cloud (#3364) * versioned old icomoon font * updated all existing icons with versioned style * Revert "updated all existing icons with versioned style" This reverts commit 79b6cdf539542a5420ab3988b7ada9a0db497a23. * versioned icon shortcode * update icons and new styles for clockface v3 * updated nav-icon shortcode and styles * updated account nav icon styles * misc updates * general style updates * updated oss versions on the homepage * fixed tick card colors on homepage Co-authored-by: Kelly Co-authored-by: pierwill <19642016+pierwill@users.noreply.github.com> Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> Co-authored-by: noramullen1 <42354779+noramullen1@users.noreply.github.com> Co-authored-by: Greg <2653109+glinton@users.noreply.github.com> Co-authored-by: Daniel Moran Co-authored-by: Jason Stirnaman Co-authored-by: Samantha Wang <32681364+sjwang90@users.noreply.github.com> Co-authored-by: Joshua Powers Co-authored-by: bgilmore-iot <85192039+bgilmore-iot@users.noreply.github.com> --- CONTRIBUTING.md | 18 +- api-docs/cloud/ref.yml | 132 +- api-docs/openapi/content/cloud/tags.yml | 5 +- api-docs/openapi/content/v2.1/info.yml | 3 + .../openapi/content/v2.1/security-schemes.yml | 58 + api-docs/openapi/content/v2.1/tag-groups.yml | 28 + api-docs/openapi/content/v2.1/tags.yml | 43 + api-docs/openapi/plugins/docs-plugin.js | 2 - api-docs/v2.0/ref.yml | 16812 ++++++++-------- api-docs/v2.1/ref.yml | 13128 ++++++++++++ api-docs/v2.1/swaggerV1Compat.yml | 329 + assets/styles/layouts/_api-overrides.scss | 16 +- assets/styles/layouts/_article.scss | 12 +- assets/styles/layouts/_error-page.scss | 2 +- assets/styles/layouts/_global.scss | 2 +- assets/styles/layouts/_inline-icons.scss | 110 +- assets/styles/layouts/_sidebar-toggle.scss | 2 +- assets/styles/layouts/_sidebar.scss | 45 +- assets/styles/layouts/_top-nav.scss | 11 +- assets/styles/layouts/_url-selector.scss | 2 +- assets/styles/layouts/article/_buttons.scss | 6 +- assets/styles/layouts/article/_children.scss | 2 +- assets/styles/layouts/article/_code.scss | 2 +- assets/styles/layouts/article/_feedback.scss | 8 +- assets/styles/layouts/article/_flux.scss | 11 - .../layouts/article/_html-diagrams.scss | 2 +- .../layouts/article/_pagination-btns.scss | 4 +- assets/styles/layouts/article/_svgs.scss | 18 - .../layouts/article/_tabbed-content.scss | 4 +- assets/styles/layouts/article/_title.scss | 35 + assets/styles/layouts/article/_warn.scss | 2 +- assets/styles/styles-default.scss | 3 +- assets/styles/themes/_theme-dark.scss | 29 +- assets/styles/themes/_theme-light.scss | 15 +- assets/styles/tools/_color-palette.scss | 18 + .../tools/{_icomoon.scss => _icomoon-v2.scss} | 14 +- assets/styles/tools/_icon.scss | 525 + assets/styles/tools/_tooltips.scss | 3 - config.staging.toml | 2 + config.toml | 1 + .../v1.9/guides/advanced-kapacitor.md | 6 +- .../chronograf/v1.9/guides/analyzing-logs.md | 4 +- .../guides/configuring-alert-endpoints.md | 2 +- .../v1.9/guides/create-a-dashboard.md | 6 +- .../v1.9/guides/write-to-influxdb.md | 6 +- .../monitor/monitor-with-cloud.md | 6 +- .../monitor/monitor-with-oss.md | 6 +- .../v1.9/flux/optimize-queries.md | 44 +- content/example.md | 113 +- .../flux/v0.x/stdlib/universe/tripleema.md | 2 +- content/influxdb/cloud/get-started.md | 8 +- content/influxdb/cloud/notebooks/_index.md | 6 +- .../influxdb/cloud/notebooks/clean-data.md | 29 +- .../cloud/notebooks/create-notebook.md | 103 +- .../influxdb/cloud/notebooks/downsample.md | 2 +- .../cloud/notebooks/manage-notebooks.md | 19 +- content/influxdb/cloud/notebooks/overview.md | 76 +- .../cloud/notebooks/troubleshoot-notebooks.md | 9 +- .../cloud/reference/api/influxdb-1x/_index.md | 23 +- .../cloud/reference/cli/influx/_index.md | 107 +- .../reference/cli/influx/apply/_index.md | 1 + .../cloud/reference/cli/influx/auth/_index.md | 1 + .../cloud/reference/cli/influx/auth/create.md | 1 + .../reference/cli/influx/backup/_index.md | 6 +- .../cli/influx/bucket-schema/_index.md | 25 +- .../cli/influx/bucket-schema/create.md | 78 +- .../cli/influx/bucket-schema/list.md | 48 +- .../cli/influx/bucket-schema/update.md | 85 +- .../reference/cli/influx/bucket/_index.md | 1 + .../reference/cli/influx/bucket/create.md | 1 + .../cloud/reference/cli/influx/bucket/list.md | 1 + .../reference/cli/influx/completion/_index.md | 1 + .../reference/cli/influx/config/_index.md | 1 + .../reference/cli/influx/dashboards/_index.md | 1 + .../reference/cli/influx/delete/_index.md | 2 + .../reference/cli/influx/export/_index.md | 1 + .../cloud/reference/cli/influx/export/all.md | 2 + .../cloud/reference/cli/influx/help/_index.md | 1 + .../cloud/reference/cli/influx/org/_index.md | 1 + .../cloud/reference/cli/influx/org/create.md | 9 + .../cloud/reference/cli/influx/org/delete.md | 9 + .../cli/influx/org/members/_index.md | 3 +- .../cloud/reference/cli/influx/ping/_index.md | 3 +- .../reference/cli/influx/query/_index.md | 2 + .../reference/cli/influx/restore/index.md | 71 +- .../reference/cli/influx/secret/_index.md | 11 +- .../reference/cli/influx/secret/delete.md | 1 - .../cloud/reference/cli/influx/secret/list.md | 1 - .../reference/cli/influx/secret/update.md | 1 - .../reference/cli/influx/setup/_index.md | 4 +- .../reference/cli/influx/stacks/_index.md | 1 + .../reference/cli/influx/stacks/update.md | 1 + .../cloud/reference/cli/influx/task/_index.md | 1 + .../reference/cli/influx/task/retry-failed.md | 1 + .../reference/cli/influx/telegrafs/_index.md | 1 + .../reference/cli/influx/template/_index.md | 1 + .../reference/cli/influx/transpile/_index.md | 12 + .../cloud/reference/cli/influx/user/_index.md | 3 +- .../cloud/reference/cli/influx/user/create.md | 2 +- .../cloud/reference/cli/influx/user/delete.md | 6 +- .../cloud/reference/cli/influx/user/list.md | 4 +- .../reference/cli/influx/user/password.md | 2 +- .../cloud/reference/cli/influx/user/update.md | 2 +- .../cloud/reference/cli/influx/v1/_index.md | 1 + .../reference/cli/influx/v1/auth/create.md | 1 + .../cli/influx/v1/auth/set-password.md | 1 + .../reference/cli/influx/v1/dbrp/_index.md | 2 + .../influx/{version.md => version/_index.md} | 1 + .../reference/cli/influx/write/_index.md | 2 + .../reference/release-notes/influx-cli.md | 97 +- content/influxdb/cloud/sign-up.md | 8 +- content/influxdb/cloud/tools/clis.md | 18 - content/influxdb/cloud/tools/influx-cli.md | 18 + content/influxdb/cloud/upgrade/v2-to-cloud.md | 2 +- .../visualization-types/band.md | 163 +- .../visualization-types/graph-single-stat.md | 124 +- .../visualization-types/graph.md | 101 +- .../v1.8/query_language/explore-schema.md | 5 + .../v2.0/influxdb-templates/monitor.md | 10 +- .../v2.0/monitor-alert/checks/create.md | 10 +- .../v2.0/monitor-alert/checks/delete.md | 4 +- .../v2.0/monitor-alert/checks/update.md | 10 +- .../v2.0/monitor-alert/checks/view.md | 6 +- .../v2.0/monitor-alert/custom-checks.md | 4 +- .../notification-endpoints/create.md | 4 +- .../notification-endpoints/delete.md | 4 +- .../notification-endpoints/update.md | 14 +- .../notification-endpoints/view.md | 8 +- .../notification-rules/create.md | 8 +- .../notification-rules/delete.md | 4 +- .../notification-rules/update.md | 14 +- .../monitor-alert/notification-rules/view.md | 6 +- .../influxdb/v2.0/monitor-alert/send-email.md | 4 +- .../templates/infrastructure/aws.md | 2 +- .../templates/infrastructure/docker.md | 2 +- .../templates/infrastructure/vshpere.md | 2 +- .../templates/infrastructure/windows.md | 2 +- .../templates/networks/haproxy.md | 2 +- .../organizations/buckets/create-bucket.md | 6 +- .../organizations/buckets/delete-bucket.md | 4 +- .../organizations/buckets/update-bucket.md | 4 +- .../organizations/buckets/view-buckets.md | 2 +- .../influxdb/v2.0/organizations/create-org.md | 2 +- .../influxdb/v2.0/organizations/delete-org.md | 2 +- .../v2.0/organizations/members/add-member.md | 2 +- .../organizations/members/remove-member.md | 4 +- .../organizations/members/view-members.md | 2 +- .../influxdb/v2.0/organizations/switch-org.md | 2 +- .../influxdb/v2.0/organizations/update-org.md | 2 +- .../influxdb/v2.0/organizations/view-orgs.md | 2 +- .../process-data/manage-tasks/create-task.md | 14 +- .../process-data/manage-tasks/delete-task.md | 2 +- .../process-data/manage-tasks/export-task.md | 4 +- .../process-data/manage-tasks/run-task.md | 4 +- .../manage-tasks/task-run-history.md | 4 +- .../process-data/manage-tasks/update-task.md | 6 +- .../process-data/manage-tasks/view-tasks.md | 4 +- .../execute-queries/data-explorer.md | 8 +- .../execute-queries/query-sample-data.md | 10 +- .../v2.0/query-data/flux/monitor-states.md | 2 +- .../v2.0/query-data/optimize-queries.md | 54 +- .../v2.0/reference/cli/influxd/_index.md | 3 +- .../influxdb/v2.0/reference/config-options.md | 185 +- .../v2.0/security/tokens/create-token.md | 4 +- .../v2.0/security/tokens/delete-token.md | 2 +- .../v2.0/security/tokens/update-tokens.md | 8 +- .../v2.0/security/tokens/view-tokens.md | 2 +- .../influxdb/v2.0/telegraf-configs/clone.md | 2 +- .../influxdb/v2.0/telegraf-configs/remove.md | 2 +- .../influxdb/v2.0/telegraf-configs/update.md | 2 +- content/influxdb/v2.0/tools/chronograf.md | 4 +- .../dashboards/control-dashboard.md | 12 +- .../dashboards/create-dashboard.md | 16 +- .../dashboards/delete-dashboard.md | 4 +- .../dashboards/export-dashboard.md | 4 +- .../influxdb/v2.0/visualize-data/labels.md | 8 +- .../variables/create-variable.md | 8 +- .../variables/delete-variable.md | 4 +- .../variables/export-variable.md | 4 +- .../variables/update-variable.md | 2 +- .../variables/view-variables.md | 4 +- .../visualization-types/band.md | 6 +- .../visualization-types/gauge.md | 2 +- .../visualization-types/graph-single-stat.md | 2 +- .../visualization-types/graph.md | 2 +- .../visualization-types/heatmap.md | 2 +- .../visualization-types/histogram.md | 2 +- .../visualization-types/mosaic.md | 2 +- .../visualization-types/scatter.md | 2 +- .../visualization-types/single-stat.md | 2 +- .../visualization-types/table.md | 2 +- .../influxdb/v2.0/write-data/delete-data.md | 2 +- .../v2.0/write-data/no-code/load-data.md | 6 +- .../manage-scrapers/create-a-scraper.md | 2 +- .../manage-scrapers/delete-a-scraper.md | 2 +- .../manage-scrapers/update-a-scraper.md | 2 +- .../no-code/use-telegraf/auto-config.md | 4 +- content/influxdb/v2.1/_index.md | 19 + content/influxdb/v2.1/api-guide/_index.md | 33 + content/influxdb/v2.1/api-guide/api_intro.md | 75 + .../v2.1/api-guide/client-libraries/_index.md | 26 + .../api-guide/client-libraries/arduino.md | 14 + .../api-guide/client-libraries/browserjs.md | 118 + .../v2.1/api-guide/client-libraries/csharp.md | 13 + .../v2.1/api-guide/client-libraries/go.md | 206 + .../v2.1/api-guide/client-libraries/java.md | 13 + .../v2.1/api-guide/client-libraries/kotlin.md | 13 + .../client-libraries/nodejs/_index.md | 23 + .../client-libraries/nodejs/install.md | 97 + .../client-libraries/nodejs/query.md | 94 + .../client-libraries/nodejs/write.md | 117 + .../v2.1/api-guide/client-libraries/php.md | 13 + .../v2.1/api-guide/client-libraries/python.md | 176 + .../v2.1/api-guide/client-libraries/r.md | 13 + .../v2.1/api-guide/client-libraries/ruby.md | 13 + .../v2.1/api-guide/client-libraries/scala.md | 13 + .../v2.1/api-guide/client-libraries/swift.md | 13 + content/influxdb/v2.1/api-guide/postman.md | 48 + .../influxdb/v2.1/backup-restore/_index.md | 17 + .../influxdb/v2.1/backup-restore/backup.md | 49 + .../influxdb/v2.1/backup-restore/restore.md | 141 + content/influxdb/v2.1/get-started.md | 59 + .../v2.1/influxdb-templates/_index.md | 74 + .../v2.1/influxdb-templates/create.md | 263 + .../v2.1/influxdb-templates/monitor.md | 181 + .../v2.1/influxdb-templates/stacks/_index.md | 26 + .../v2.1/influxdb-templates/stacks/init.md | 73 + .../v2.1/influxdb-templates/stacks/remove.md | 39 + .../influxdb-templates/stacks/save-time.md | 165 + .../v2.1/influxdb-templates/stacks/update.md | 56 + .../v2.1/influxdb-templates/stacks/view.md | 69 + .../influxdb/v2.1/influxdb-templates/use.md | 241 + content/influxdb/v2.1/install.md | 752 + content/influxdb/v2.1/monitor-alert/_index.md | 38 + .../v2.1/monitor-alert/checks/_index.md | 19 + .../v2.1/monitor-alert/checks/create.md | 152 + .../v2.1/monitor-alert/checks/delete.md | 34 + .../v2.1/monitor-alert/checks/update.md | 60 + .../v2.1/monitor-alert/checks/view.md | 43 + .../v2.1/monitor-alert/custom-checks.md | 102 + .../notification-endpoints/_index.md | 19 + .../notification-endpoints/create.md | 41 + .../notification-endpoints/delete.md | 26 + .../notification-endpoints/update.md | 66 + .../notification-endpoints/view.md | 51 + .../notification-rules/_index.md | 17 + .../notification-rules/create.md | 44 + .../notification-rules/delete.md | 22 + .../notification-rules/update.md | 50 + .../monitor-alert/notification-rules/view.md | 45 + .../influxdb/v2.1/monitor-alert/send-email.md | 273 + .../v2.1/monitor-alert/templates/_index.md | 14 + .../templates/infrastructure/_index.md | 14 + .../templates/infrastructure/aws.md | 57 + .../templates/infrastructure/docker.md | 54 + .../templates/infrastructure/vshpere.md | 55 + .../templates/infrastructure/windows.md | 52 + .../templates/networks/_index.md | 14 + .../templates/networks/haproxy.md | 48 + content/influxdb/v2.1/notebooks/_index.md | 17 + content/influxdb/v2.1/notebooks/clean-data.md | 40 + .../v2.1/notebooks/create-notebook.md | 109 + .../v2.1/notebooks/manage-notebooks.md | 29 + content/influxdb/v2.1/notebooks/overview.md | 81 + .../v2.1/notebooks/troubleshoot-notebooks.md | 19 + content/influxdb/v2.1/organizations/_index.md | 17 + .../v2.1/organizations/buckets/_index.md | 20 + .../organizations/buckets/create-bucket.md | 108 + .../organizations/buckets/delete-bucket.md | 56 + .../organizations/buckets/update-bucket.md | 75 + .../organizations/buckets/view-buckets.md | 34 + .../influxdb/v2.1/organizations/create-org.md | 47 + .../influxdb/v2.1/organizations/delete-org.md | 41 + .../v2.1/organizations/members/_index.md | 16 + .../v2.1/organizations/members/add-member.md | 36 + .../organizations/members/remove-member.md | 44 + .../organizations/members/view-members.md | 35 + .../influxdb/v2.1/organizations/switch-org.md | 22 + .../influxdb/v2.1/organizations/update-org.md | 49 + .../influxdb/v2.1/organizations/view-orgs.md | 58 + content/influxdb/v2.1/process-data/_index.md | 26 + .../v2.1/process-data/common-tasks/_index.md | 17 + .../common-tasks/calculate_weekly_mean.md | 49 + .../common-tasks/convert_results_to_json.md | 43 + .../common-tasks/downsample-data.md | 79 + .../influxdb/v2.1/process-data/get-started.md | 163 + .../v2.1/process-data/manage-tasks/_index.md | 20 + .../process-data/manage-tasks/create-task.md | 152 + .../process-data/manage-tasks/delete-task.md | 36 + .../process-data/manage-tasks/export-task.md | 26 + .../process-data/manage-tasks/run-task.md | 66 + .../manage-tasks/task-run-history.md | 67 + .../process-data/manage-tasks/update-task.md | 69 + .../process-data/manage-tasks/view-tasks.md | 38 + .../v2.1/process-data/task-options.md | 107 + content/influxdb/v2.1/query-data/_index.md | 17 + .../v2.1/query-data/common-queries/_index.md | 22 + .../common-queries/compare-values.md | 48 + .../common-queries/iot-common-queries.md | 215 + .../multiple-fields-in-calculations.md | 110 + .../common-queries/operate-on-columns.md | 140 + .../v2.1/query-data/execute-queries/_index.md | 17 + .../execute-queries/data-explorer.md | 101 + .../query-data/execute-queries/flux-repl.md | 19 + .../query-data/execute-queries/influx-api.md | 105 + .../execute-queries/influx-query.md | 41 + .../execute-queries/query-sample-data.md | 89 + .../influxdb/v2.1/query-data/flux/_index.md | 38 + .../query-data/flux/calculate-percentages.md | 215 + .../v2.1/query-data/flux/conditional-logic.md | 208 + .../v2.1/query-data/flux/cumulativesum.md | 70 + .../flux/custom-functions/_index.md | 226 + .../flux/custom-functions/custom-aggregate.md | 258 + .../influxdb/v2.1/query-data/flux/exists.md | 86 + .../v2.1/query-data/flux/explore-schema.md | 140 + content/influxdb/v2.1/query-data/flux/fill.md | 113 + .../v2.1/query-data/flux/first-last.md | 151 + .../v2.1/query-data/flux/geo/_index.md | 69 + .../query-data/flux/geo/filter-by-region.md | 130 + .../query-data/flux/geo/group-geo-data.md | 79 + .../query-data/flux/geo/shape-geo-data.md | 121 + .../v2.1/query-data/flux/group-data.md | 678 + .../v2.1/query-data/flux/histograms.md | 197 + .../influxdb/v2.1/query-data/flux/increase.md | 57 + content/influxdb/v2.1/query-data/flux/join.md | 315 + .../query-data/flux/manipulate-timestamps.md | 218 + .../query-data/flux/mathematic-operations.md | 235 + .../influxdb/v2.1/query-data/flux/median.md | 149 + .../v2.1/query-data/flux/monitor-states.md | 199 + .../v2.1/query-data/flux/moving-average.md | 121 + .../query-data/flux/percentile-quantile.md | 165 + .../v2.1/query-data/flux/query-fields.md | 82 + content/influxdb/v2.1/query-data/flux/rate.md | 176 + .../query-data/flux/regular-expressions.md | 97 + .../v2.1/query-data/flux/scalar-values.md | 236 + .../v2.1/query-data/flux/sort-limit.md | 74 + content/influxdb/v2.1/query-data/flux/sql.md | 384 + .../v2.1/query-data/flux/window-aggregate.md | 360 + .../v2.1/query-data/get-started/_index.md | 35 + .../query-data/get-started/query-influxdb.md | 141 + .../query-data/get-started/transform-data.md | 186 + content/influxdb/v2.1/query-data/influxql.md | 250 + .../v2.1/query-data/optimize-queries.md | 191 + content/influxdb/v2.1/reference/_index.md | 8 + content/influxdb/v2.1/reference/api/_index.md | 30 + .../v2.1/reference/api/influxdb-1x/_index.md | 163 + .../v2.1/reference/api/influxdb-1x/dbrp.md | 58 + .../v2.1/reference/api/influxdb-1x/query.md | 143 + .../v2.1/reference/api/influxdb-1x/write.md | 133 + content/influxdb/v2.1/reference/cli/_index.md | 18 + .../v2.1/reference/cli/influx/_index.md | 133 + .../v2.1/reference/cli/influx/apply/_index.md | 132 + .../v2.1/reference/cli/influx/auth/_index.md | 41 + .../v2.1/reference/cli/influx/auth/active.md | 40 + .../v2.1/reference/cli/influx/auth/create.md | 140 + .../v2.1/reference/cli/influx/auth/delete.md | 39 + .../reference/cli/influx/auth/inactive.md | 47 + .../v2.1/reference/cli/influx/auth/list.md | 53 + .../reference/cli/influx/backup/_index.md | 66 + .../cli/influx/bucket-schema/_index.md | 47 + .../cli/influx/bucket-schema/create.md | 90 + .../cli/influx/bucket-schema/list.md | 59 + .../cli/influx/bucket-schema/update.md | 96 + .../reference/cli/influx/bucket/_index.md | 43 + .../reference/cli/influx/bucket/create.md | 107 + .../reference/cli/influx/bucket/delete.md | 53 + .../v2.1/reference/cli/influx/bucket/list.md | 66 + .../reference/cli/influx/bucket/update.md | 74 + .../reference/cli/influx/completion/_index.md | 61 + .../reference/cli/influx/config/_index.md | 65 + .../reference/cli/influx/config/create.md | 49 + .../v2.1/reference/cli/influx/config/list.md | 29 + .../v2.1/reference/cli/influx/config/rm.md | 42 + .../v2.1/reference/cli/influx/config/set.md | 49 + .../reference/cli/influx/dashboards/_index.md | 54 + .../reference/cli/influx/delete/_index.md | 78 + .../reference/cli/influx/export/_index.md | 111 + .../v2.1/reference/cli/influx/export/all.md | 87 + .../v2.1/reference/cli/influx/export/stack.md | 51 + .../v2.1/reference/cli/influx/help/_index.md | 25 + .../v2.1/reference/cli/influx/org/_index.md | 40 + .../v2.1/reference/cli/influx/org/create.md | 47 + .../v2.1/reference/cli/influx/org/delete.md | 39 + .../v2.1/reference/cli/influx/org/list.md | 59 + .../cli/influx/org/members/_index.md | 30 + .../reference/cli/influx/org/members/add.md | 38 + .../reference/cli/influx/org/members/list.md | 39 + .../cli/influx/org/members/remove.md | 39 + .../v2.1/reference/cli/influx/org/update.md | 50 + .../v2.1/reference/cli/influx/ping/_index.md | 35 + .../v2.1/reference/cli/influx/query/_index.md | 87 + .../v2.1/reference/cli/influx/repl/_index.md | 44 + .../reference/cli/influx/restore/index.md | 95 + .../reference/cli/influx/secret/_index.md | 36 + .../reference/cli/influx/secret/delete.md | 42 + .../v2.1/reference/cli/influx/secret/list.md | 44 + .../reference/cli/influx/secret/update.md | 61 + .../v2.1/reference/cli/influx/setup/_index.md | 70 + .../reference/cli/influx/stacks/_index.md | 79 + .../v2.1/reference/cli/influx/stacks/init.md | 53 + .../reference/cli/influx/stacks/remove.md | 48 + .../reference/cli/influx/stacks/update.md | 89 + .../v2.1/reference/cli/influx/task/_index.md | 40 + .../v2.1/reference/cli/influx/task/create.md | 59 + .../v2.1/reference/cli/influx/task/delete.md | 41 + .../v2.1/reference/cli/influx/task/list.md | 68 + .../reference/cli/influx/task/log/_index.md | 30 + .../reference/cli/influx/task/log/list.md | 52 + .../reference/cli/influx/task/retry-failed.md | 98 + .../reference/cli/influx/task/run/_index.md | 30 + .../reference/cli/influx/task/run/list.md | 66 + .../reference/cli/influx/task/run/retry.md | 45 + .../v2.1/reference/cli/influx/task/update.md | 74 + .../reference/cli/influx/telegrafs/_index.md | 62 + .../reference/cli/influx/telegrafs/create.md | 54 + .../v2.1/reference/cli/influx/telegrafs/rm.md | 48 + .../reference/cli/influx/telegrafs/update.md | 56 + .../reference/cli/influx/template/_index.md | 86 + .../reference/cli/influx/template/validate.md | 70 + .../reference/cli/influx/transpile/_index.md | 55 + .../v2.1/reference/cli/influx/user/_index.md | 39 + .../v2.1/reference/cli/influx/user/create.md | 44 + .../v2.1/reference/cli/influx/user/delete.md | 39 + .../v2.1/reference/cli/influx/user/list.md | 59 + .../reference/cli/influx/user/password.md | 48 + .../v2.1/reference/cli/influx/user/update.md | 43 + .../v2.1/reference/cli/influx/v1/_index.md | 36 + .../reference/cli/influx/v1/auth/_index.md | 47 + .../reference/cli/influx/v1/auth/create.md | 54 + .../reference/cli/influx/v1/auth/delete.md | 41 + .../v2.1/reference/cli/influx/v1/auth/list.md | 68 + .../cli/influx/v1/auth/set-active.md | 42 + .../cli/influx/v1/auth/set-inactive.md | 42 + .../cli/influx/v1/auth/set-password.md | 43 + .../reference/cli/influx/v1/dbrp/_index.md | 37 + .../reference/cli/influx/v1/dbrp/create.md | 50 + .../reference/cli/influx/v1/dbrp/delete.md | 42 + .../v2.1/reference/cli/influx/v1/dbrp/list.md | 64 + .../reference/cli/influx/v1/dbrp/update.md | 53 + .../reference/cli/influx/version/_index.md | 25 + .../v2.1/reference/cli/influx/write/_index.md | 289 + .../v2.1/reference/cli/influx/write/dryrun.md | 192 + .../v2.1/reference/cli/influxd/_index.md | 45 + .../v2.1/reference/cli/influxd/downgrade.md | 48 + .../reference/cli/influxd/inspect/_index.md | 38 + .../cli/influxd/inspect/build-tsi.md | 59 + .../cli/influxd/inspect/delete-tsm.md | 38 + .../reference/cli/influxd/inspect/dump-tsi.md | 32 + .../reference/cli/influxd/inspect/dump-tsm.md | 30 + .../reference/cli/influxd/inspect/dump-wal.md | 43 + .../cli/influxd/inspect/export-index.md | 26 + .../cli/influxd/inspect/export-lp.md | 133 + .../cli/influxd/inspect/report-tsi.md | 29 + .../cli/influxd/inspect/report-tsm.md | 55 + .../cli/influxd/inspect/verify-seriesfile.md | 27 + .../cli/influxd/inspect/verify-tombstone.md | 25 + .../cli/influxd/inspect/verify-tsm.md | 26 + .../cli/influxd/inspect/verify-wal.md | 40 + .../reference/cli/influxd/print-config.md | 49 + .../reference/cli/influxd/recovery/_index.md | 33 + .../cli/influxd/recovery/auth/_index.md | 30 + .../influxd/recovery/auth/create-operator.md | 41 + .../cli/influxd/recovery/auth/list.md | 28 + .../cli/influxd/recovery/org/_index.md | 30 + .../cli/influxd/recovery/org/create.md | 36 + .../cli/influxd/recovery/org/list.md | 28 + .../cli/influxd/recovery/user/_index.md | 31 + .../cli/influxd/recovery/user/create.md | 39 + .../cli/influxd/recovery/user/list.md | 28 + .../v2.1/reference/cli/influxd/run.md | 40 + .../v2.1/reference/cli/influxd/upgrade.md | 59 + .../v2.1/reference/cli/influxd/version.md | 24 + .../influxdb/v2.1/reference/config-options.md | 3418 ++++ .../v2.1/reference/contributing/_index.md | 26 + content/influxdb/v2.1/reference/glossary.md | 1222 ++ .../v2.1/reference/internals/_index.md | 9 + .../reference/internals/file-system-layout.md | 260 + .../v2.1/reference/internals/shards.md | 145 + .../reference/internals/storage-engine.md | 104 + .../reference/internals/system-buckets.md | 93 + .../v2.1/reference/key-concepts/_index.md | 14 + .../reference/key-concepts/data-elements.md | 201 + .../reference/key-concepts/data-schema.md | 63 + .../key-concepts/design-principles.md | 44 + .../v2.1/reference/prometheus-metrics.md | 286 + .../v2.1/reference/release-notes/_index.md | 12 + .../reference/release-notes/influx-cli.md | 107 + .../v2.1/reference/release-notes/influxdb.md | 1626 ++ .../release-notes/supported-release.md | 36 + .../influxdb/v2.1/reference/sample-data.md | 161 + .../influxdb/v2.1/reference/syntax/_index.md | 18 + .../reference/syntax/annotated-csv/_index.md | 311 + .../syntax/annotated-csv/extended.md | 396 + .../v2.1/reference/syntax/delete-predicate.md | 82 + .../v2.1/reference/syntax/flux/_index.md | 29 + .../reference/syntax/flux/flux-vs-influxql.md | 405 + .../v2.1/reference/syntax/line-protocol.md | 283 + .../v2.1/reference/telegraf-plugins.md | 12 + content/influxdb/v2.1/reference/urls.md | 45 + content/influxdb/v2.1/security/_index.md | 25 + content/influxdb/v2.1/security/enable-tls.md | 154 + .../influxdb/v2.1/security/secrets/_index.md | 24 + content/influxdb/v2.1/security/secrets/add.md | 58 + .../influxdb/v2.1/security/secrets/delete.md | 50 + .../influxdb/v2.1/security/secrets/update.md | 57 + .../v2.1/security/secrets/use-vault.md | 98 + content/influxdb/v2.1/security/secrets/use.md | 29 + .../influxdb/v2.1/security/secrets/view.md | 39 + .../influxdb/v2.1/security/tokens/_index.md | 43 + .../v2.1/security/tokens/create-token.md | 115 + .../v2.1/security/tokens/delete-token.md | 39 + .../v2.1/security/tokens/update-tokens.md | 31 + .../v2.1/security/tokens/use-tokens.md | 44 + .../v2.1/security/tokens/view-tokens.md | 77 + content/influxdb/v2.1/tags/_index.md | 4 + .../influxdb/v2.1/telegraf-configs/_index.md | 37 + .../influxdb/v2.1/telegraf-configs/clone.md | 21 + .../influxdb/v2.1/telegraf-configs/create.md | 72 + .../influxdb/v2.1/telegraf-configs/remove.md | 53 + .../influxdb/v2.1/telegraf-configs/update.md | 102 + .../influxdb/v2.1/telegraf-configs/view.md | 45 + content/influxdb/v2.1/tools/_index.md | 11 + content/influxdb/v2.1/tools/chronograf.md | 97 + content/influxdb/v2.1/tools/flux-vim-lsp.md | 111 + content/influxdb/v2.1/tools/flux-vscode.md | 83 + .../influxdb/v2.1/tools/google-data-studio.md | 35 + content/influxdb/v2.1/tools/grafana.md | 256 + content/influxdb/v2.1/tools/influx-cli.md | 230 + content/influxdb/v2.1/tools/kapacitor.md | 139 + content/influxdb/v2.1/tools/repl.md | 53 + content/influxdb/v2.1/upgrade/_index.md | 12 + content/influxdb/v2.1/upgrade/downgrade.md | 42 + .../influxdb/v2.1/upgrade/v1-to-v2/_index.md | 28 + .../upgrade/v1-to-v2/automatic-upgrade.md | 266 + .../influxdb/v2.1/upgrade/v1-to-v2/docker.md | 251 + .../v2.1/upgrade/v1-to-v2/manual-upgrade.md | 339 + .../v2.1/upgrade/v1-to-v2/migrate-cqs.md | 381 + content/influxdb/v2.1/upgrade/v2-to-v2.md | 81 + content/influxdb/v2.1/users/_index.md | 26 + .../influxdb/v2.1/users/change-password.md | 35 + content/influxdb/v2.1/users/create-user.md | 51 + content/influxdb/v2.1/users/delete-user.md | 41 + content/influxdb/v2.1/users/update-user.md | 36 + content/influxdb/v2.1/users/view-users.md | 33 + .../influxdb/v2.1/visualize-data/_index.md | 16 + .../v2.1/visualize-data/annotations.md | 68 + .../v2.1/visualize-data/dashboards/_index.md | 37 + .../dashboards/control-dashboard.md | 67 + .../dashboards/create-dashboard.md | 58 + .../dashboards/delete-dashboard.md | 23 + .../dashboards/export-dashboard.md | 26 + .../influxdb/v2.1/visualize-data/labels.md | 44 + .../v2.1/visualize-data/variables/_index.md | 73 + .../variables/common-variables.md | 112 + .../variables/create-variable.md | 73 + .../variables/delete-variable.md | 26 + .../variables/export-variable.md | 27 + .../variables/update-variable.md | 23 + .../variables/variable-types.md | 97 + .../variables/view-variables.md | 31 + .../visualization-types/_index.md | 17 + .../visualization-types/band.md | 174 + .../visualization-types/gauge.md | 67 + .../visualization-types/graph-single-stat.md | 140 + .../visualization-types/graph.md | 113 + .../visualization-types/heatmap.md | 134 + .../visualization-types/histogram.md | 87 + .../visualization-types/mosaic.md | 76 + .../visualization-types/scatter.md | 136 + .../visualization-types/single-stat.md | 65 + .../visualization-types/table.md | 78 + content/influxdb/v2.1/write-data/_index.md | 30 + .../v2.1/write-data/best-practices/_index.md | 17 + .../best-practices/duplicate-points.md | 131 + .../best-practices/optimize-writes.md | 132 + .../resolve-high-cardinality.md | 117 + .../best-practices/schema-design.md | 228 + .../influxdb/v2.1/write-data/delete-data.md | 143 + .../v2.1/write-data/developer-tools/_index.md | 16 + .../v2.1/write-data/developer-tools/api.md | 57 + .../developer-tools/client-libraries.md | 15 + .../v2.1/write-data/developer-tools/csv.md | 596 + .../write-data/developer-tools/influx-cli.md | 56 + .../scrape-prometheus-metrics.md | 105 + .../developer-tools/third-party-solutions.md | 61 + .../v2.1/write-data/no-code/_index.md | 17 + .../v2.1/write-data/no-code/load-data.md | 79 + .../write-data/no-code/scrape-data/_index.md | 31 + .../scrape-data/manage-scrapers/_index.md | 17 + .../manage-scrapers/create-a-scraper.md | 31 + .../manage-scrapers/delete-a-scraper.md | 23 + .../manage-scrapers/update-a-scraper.md | 28 + .../scrape-data/scrapable-endpoints.md | 45 + .../v2.1/write-data/no-code/third-party.md | 92 + .../write-data/no-code/use-telegraf/_index.md | 36 + .../no-code/use-telegraf/auto-config.md | 136 + .../no-code/use-telegraf/manual-config.md | 161 + .../use-telegraf-plugins/_index.md | 16 + .../use-telegraf-plugins/use-http-plugin.md | 119 + .../influxdb/v2.1/write-data/troubleshoot.md | 79 + data/influxd_flags.yml | 212 + data/products.yml | 10 +- deploy/edge.js | 4 +- layouts/index.html | 2 +- layouts/partials/article.html | 1 + layouts/partials/article/page-meta.html | 8 + layouts/partials/header/google-fonts.html | 4 +- layouts/partials/topnav.html | 6 +- layouts/shortcodes/caps.html | 1 + layouts/shortcodes/cli/influxd-flags.html | 12 + layouts/shortcodes/cli/influxd-flags.md | 56 - layouts/shortcodes/current-version.html | 3 + layouts/shortcodes/expand.html | 2 +- layouts/shortcodes/icon.html | 227 +- .../influxdb/install-old-versions.html | 12 + layouts/shortcodes/latest-patch.html | 16 +- layouts/shortcodes/nav-icon.html | 196 +- .../api/v1-compat/auth/cloud/basic-auth.js | 2 +- .../api/v1-compat/auth/cloud/basic-auth.sh | 6 +- .../v1-compat/auth/cloud/querystring-auth.js | 38 + .../v1-compat/auth/cloud/querystring-auth.sh | 14 + static/fonts/icomoon-v2.eot | Bin 0 -> 18516 bytes static/fonts/icomoon-v2.svg | 86 + static/fonts/icomoon-v2.ttf | Bin 0 -> 18352 bytes static/fonts/icomoon-v2.woff | Bin 0 -> 18428 bytes static/fonts/icomoon.eot | Bin 18516 -> 33676 bytes static/fonts/icomoon.svg | 244 +- static/fonts/icomoon.ttf | Bin 18352 -> 33512 bytes static/fonts/icomoon.woff | Bin 18428 -> 33588 bytes static/fonts/icomoon.woff2 | Bin 0 -> 15952 bytes 630 files changed, 63299 insertions(+), 10625 deletions(-) create mode 100644 api-docs/openapi/content/v2.1/info.yml create mode 100644 api-docs/openapi/content/v2.1/security-schemes.yml create mode 100644 api-docs/openapi/content/v2.1/tag-groups.yml create mode 100644 api-docs/openapi/content/v2.1/tags.yml create mode 100644 api-docs/v2.1/ref.yml create mode 100644 api-docs/v2.1/swaggerV1Compat.yml create mode 100644 assets/styles/layouts/article/_title.scss rename assets/styles/tools/{_icomoon.scss => _icomoon-v2.scss} (91%) create mode 100644 assets/styles/tools/_icon.scss rename content/influxdb/cloud/reference/cli/influx/{version.md => version/_index.md} (89%) delete mode 100644 content/influxdb/cloud/tools/clis.md create mode 100644 content/influxdb/cloud/tools/influx-cli.md create mode 100644 content/influxdb/v2.1/_index.md create mode 100644 content/influxdb/v2.1/api-guide/_index.md create mode 100644 content/influxdb/v2.1/api-guide/api_intro.md create mode 100644 content/influxdb/v2.1/api-guide/client-libraries/_index.md create mode 100644 content/influxdb/v2.1/api-guide/client-libraries/arduino.md create mode 100644 content/influxdb/v2.1/api-guide/client-libraries/browserjs.md create mode 100644 content/influxdb/v2.1/api-guide/client-libraries/csharp.md create mode 100644 content/influxdb/v2.1/api-guide/client-libraries/go.md create mode 100644 content/influxdb/v2.1/api-guide/client-libraries/java.md create mode 100644 content/influxdb/v2.1/api-guide/client-libraries/kotlin.md create mode 100644 content/influxdb/v2.1/api-guide/client-libraries/nodejs/_index.md create mode 100644 content/influxdb/v2.1/api-guide/client-libraries/nodejs/install.md create mode 100644 content/influxdb/v2.1/api-guide/client-libraries/nodejs/query.md create mode 100644 content/influxdb/v2.1/api-guide/client-libraries/nodejs/write.md create mode 100644 content/influxdb/v2.1/api-guide/client-libraries/php.md create mode 100644 content/influxdb/v2.1/api-guide/client-libraries/python.md create mode 100644 content/influxdb/v2.1/api-guide/client-libraries/r.md create mode 100644 content/influxdb/v2.1/api-guide/client-libraries/ruby.md create mode 100644 content/influxdb/v2.1/api-guide/client-libraries/scala.md create mode 100644 content/influxdb/v2.1/api-guide/client-libraries/swift.md create mode 100644 content/influxdb/v2.1/api-guide/postman.md create mode 100644 content/influxdb/v2.1/backup-restore/_index.md create mode 100644 content/influxdb/v2.1/backup-restore/backup.md create mode 100644 content/influxdb/v2.1/backup-restore/restore.md create mode 100644 content/influxdb/v2.1/get-started.md create mode 100644 content/influxdb/v2.1/influxdb-templates/_index.md create mode 100644 content/influxdb/v2.1/influxdb-templates/create.md create mode 100644 content/influxdb/v2.1/influxdb-templates/monitor.md create mode 100644 content/influxdb/v2.1/influxdb-templates/stacks/_index.md create mode 100644 content/influxdb/v2.1/influxdb-templates/stacks/init.md create mode 100644 content/influxdb/v2.1/influxdb-templates/stacks/remove.md create mode 100644 content/influxdb/v2.1/influxdb-templates/stacks/save-time.md create mode 100644 content/influxdb/v2.1/influxdb-templates/stacks/update.md create mode 100644 content/influxdb/v2.1/influxdb-templates/stacks/view.md create mode 100644 content/influxdb/v2.1/influxdb-templates/use.md create mode 100644 content/influxdb/v2.1/install.md create mode 100644 content/influxdb/v2.1/monitor-alert/_index.md create mode 100644 content/influxdb/v2.1/monitor-alert/checks/_index.md create mode 100644 content/influxdb/v2.1/monitor-alert/checks/create.md create mode 100644 content/influxdb/v2.1/monitor-alert/checks/delete.md create mode 100644 content/influxdb/v2.1/monitor-alert/checks/update.md create mode 100644 content/influxdb/v2.1/monitor-alert/checks/view.md create mode 100644 content/influxdb/v2.1/monitor-alert/custom-checks.md create mode 100644 content/influxdb/v2.1/monitor-alert/notification-endpoints/_index.md create mode 100644 content/influxdb/v2.1/monitor-alert/notification-endpoints/create.md create mode 100644 content/influxdb/v2.1/monitor-alert/notification-endpoints/delete.md create mode 100644 content/influxdb/v2.1/monitor-alert/notification-endpoints/update.md create mode 100644 content/influxdb/v2.1/monitor-alert/notification-endpoints/view.md create mode 100644 content/influxdb/v2.1/monitor-alert/notification-rules/_index.md create mode 100644 content/influxdb/v2.1/monitor-alert/notification-rules/create.md create mode 100644 content/influxdb/v2.1/monitor-alert/notification-rules/delete.md create mode 100644 content/influxdb/v2.1/monitor-alert/notification-rules/update.md create mode 100644 content/influxdb/v2.1/monitor-alert/notification-rules/view.md create mode 100644 content/influxdb/v2.1/monitor-alert/send-email.md create mode 100644 content/influxdb/v2.1/monitor-alert/templates/_index.md create mode 100644 content/influxdb/v2.1/monitor-alert/templates/infrastructure/_index.md create mode 100644 content/influxdb/v2.1/monitor-alert/templates/infrastructure/aws.md create mode 100644 content/influxdb/v2.1/monitor-alert/templates/infrastructure/docker.md create mode 100644 content/influxdb/v2.1/monitor-alert/templates/infrastructure/vshpere.md create mode 100644 content/influxdb/v2.1/monitor-alert/templates/infrastructure/windows.md create mode 100644 content/influxdb/v2.1/monitor-alert/templates/networks/_index.md create mode 100644 content/influxdb/v2.1/monitor-alert/templates/networks/haproxy.md create mode 100644 content/influxdb/v2.1/notebooks/_index.md create mode 100644 content/influxdb/v2.1/notebooks/clean-data.md create mode 100644 content/influxdb/v2.1/notebooks/create-notebook.md create mode 100644 content/influxdb/v2.1/notebooks/manage-notebooks.md create mode 100644 content/influxdb/v2.1/notebooks/overview.md create mode 100644 content/influxdb/v2.1/notebooks/troubleshoot-notebooks.md create mode 100644 content/influxdb/v2.1/organizations/_index.md create mode 100644 content/influxdb/v2.1/organizations/buckets/_index.md create mode 100644 content/influxdb/v2.1/organizations/buckets/create-bucket.md create mode 100644 content/influxdb/v2.1/organizations/buckets/delete-bucket.md create mode 100644 content/influxdb/v2.1/organizations/buckets/update-bucket.md create mode 100644 content/influxdb/v2.1/organizations/buckets/view-buckets.md create mode 100644 content/influxdb/v2.1/organizations/create-org.md create mode 100644 content/influxdb/v2.1/organizations/delete-org.md create mode 100644 content/influxdb/v2.1/organizations/members/_index.md create mode 100644 content/influxdb/v2.1/organizations/members/add-member.md create mode 100644 content/influxdb/v2.1/organizations/members/remove-member.md create mode 100644 content/influxdb/v2.1/organizations/members/view-members.md create mode 100644 content/influxdb/v2.1/organizations/switch-org.md create mode 100644 content/influxdb/v2.1/organizations/update-org.md create mode 100644 content/influxdb/v2.1/organizations/view-orgs.md create mode 100644 content/influxdb/v2.1/process-data/_index.md create mode 100644 content/influxdb/v2.1/process-data/common-tasks/_index.md create mode 100644 content/influxdb/v2.1/process-data/common-tasks/calculate_weekly_mean.md create mode 100644 content/influxdb/v2.1/process-data/common-tasks/convert_results_to_json.md create mode 100644 content/influxdb/v2.1/process-data/common-tasks/downsample-data.md create mode 100644 content/influxdb/v2.1/process-data/get-started.md create mode 100644 content/influxdb/v2.1/process-data/manage-tasks/_index.md create mode 100644 content/influxdb/v2.1/process-data/manage-tasks/create-task.md create mode 100644 content/influxdb/v2.1/process-data/manage-tasks/delete-task.md create mode 100644 content/influxdb/v2.1/process-data/manage-tasks/export-task.md create mode 100644 content/influxdb/v2.1/process-data/manage-tasks/run-task.md create mode 100644 content/influxdb/v2.1/process-data/manage-tasks/task-run-history.md create mode 100644 content/influxdb/v2.1/process-data/manage-tasks/update-task.md create mode 100644 content/influxdb/v2.1/process-data/manage-tasks/view-tasks.md create mode 100644 content/influxdb/v2.1/process-data/task-options.md create mode 100644 content/influxdb/v2.1/query-data/_index.md create mode 100644 content/influxdb/v2.1/query-data/common-queries/_index.md create mode 100644 content/influxdb/v2.1/query-data/common-queries/compare-values.md create mode 100644 content/influxdb/v2.1/query-data/common-queries/iot-common-queries.md create mode 100644 content/influxdb/v2.1/query-data/common-queries/multiple-fields-in-calculations.md create mode 100644 content/influxdb/v2.1/query-data/common-queries/operate-on-columns.md create mode 100644 content/influxdb/v2.1/query-data/execute-queries/_index.md create mode 100644 content/influxdb/v2.1/query-data/execute-queries/data-explorer.md create mode 100644 content/influxdb/v2.1/query-data/execute-queries/flux-repl.md create mode 100644 content/influxdb/v2.1/query-data/execute-queries/influx-api.md create mode 100644 content/influxdb/v2.1/query-data/execute-queries/influx-query.md create mode 100644 content/influxdb/v2.1/query-data/execute-queries/query-sample-data.md create mode 100644 content/influxdb/v2.1/query-data/flux/_index.md create mode 100644 content/influxdb/v2.1/query-data/flux/calculate-percentages.md create mode 100644 content/influxdb/v2.1/query-data/flux/conditional-logic.md create mode 100644 content/influxdb/v2.1/query-data/flux/cumulativesum.md create mode 100644 content/influxdb/v2.1/query-data/flux/custom-functions/_index.md create mode 100644 content/influxdb/v2.1/query-data/flux/custom-functions/custom-aggregate.md create mode 100644 content/influxdb/v2.1/query-data/flux/exists.md create mode 100644 content/influxdb/v2.1/query-data/flux/explore-schema.md create mode 100644 content/influxdb/v2.1/query-data/flux/fill.md create mode 100644 content/influxdb/v2.1/query-data/flux/first-last.md create mode 100644 content/influxdb/v2.1/query-data/flux/geo/_index.md create mode 100644 content/influxdb/v2.1/query-data/flux/geo/filter-by-region.md create mode 100644 content/influxdb/v2.1/query-data/flux/geo/group-geo-data.md create mode 100644 content/influxdb/v2.1/query-data/flux/geo/shape-geo-data.md create mode 100644 content/influxdb/v2.1/query-data/flux/group-data.md create mode 100644 content/influxdb/v2.1/query-data/flux/histograms.md create mode 100644 content/influxdb/v2.1/query-data/flux/increase.md create mode 100644 content/influxdb/v2.1/query-data/flux/join.md create mode 100644 content/influxdb/v2.1/query-data/flux/manipulate-timestamps.md create mode 100644 content/influxdb/v2.1/query-data/flux/mathematic-operations.md create mode 100644 content/influxdb/v2.1/query-data/flux/median.md create mode 100644 content/influxdb/v2.1/query-data/flux/monitor-states.md create mode 100644 content/influxdb/v2.1/query-data/flux/moving-average.md create mode 100644 content/influxdb/v2.1/query-data/flux/percentile-quantile.md create mode 100644 content/influxdb/v2.1/query-data/flux/query-fields.md create mode 100644 content/influxdb/v2.1/query-data/flux/rate.md create mode 100644 content/influxdb/v2.1/query-data/flux/regular-expressions.md create mode 100644 content/influxdb/v2.1/query-data/flux/scalar-values.md create mode 100644 content/influxdb/v2.1/query-data/flux/sort-limit.md create mode 100644 content/influxdb/v2.1/query-data/flux/sql.md create mode 100644 content/influxdb/v2.1/query-data/flux/window-aggregate.md create mode 100644 content/influxdb/v2.1/query-data/get-started/_index.md create mode 100644 content/influxdb/v2.1/query-data/get-started/query-influxdb.md create mode 100644 content/influxdb/v2.1/query-data/get-started/transform-data.md create mode 100644 content/influxdb/v2.1/query-data/influxql.md create mode 100644 content/influxdb/v2.1/query-data/optimize-queries.md create mode 100644 content/influxdb/v2.1/reference/_index.md create mode 100644 content/influxdb/v2.1/reference/api/_index.md create mode 100644 content/influxdb/v2.1/reference/api/influxdb-1x/_index.md create mode 100644 content/influxdb/v2.1/reference/api/influxdb-1x/dbrp.md create mode 100644 content/influxdb/v2.1/reference/api/influxdb-1x/query.md create mode 100644 content/influxdb/v2.1/reference/api/influxdb-1x/write.md create mode 100644 content/influxdb/v2.1/reference/cli/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/apply/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/auth/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/auth/active.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/auth/create.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/auth/delete.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/auth/inactive.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/auth/list.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/backup/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/bucket-schema/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/bucket-schema/create.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/bucket-schema/list.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/bucket-schema/update.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/bucket/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/bucket/create.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/bucket/delete.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/bucket/list.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/bucket/update.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/completion/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/config/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/config/create.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/config/list.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/config/rm.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/config/set.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/dashboards/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/delete/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/export/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/export/all.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/export/stack.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/help/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/org/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/org/create.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/org/delete.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/org/list.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/org/members/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/org/members/add.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/org/members/list.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/org/members/remove.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/org/update.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/ping/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/query/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/repl/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/restore/index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/secret/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/secret/delete.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/secret/list.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/secret/update.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/setup/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/stacks/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/stacks/init.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/stacks/remove.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/stacks/update.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/task/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/task/create.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/task/delete.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/task/list.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/task/log/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/task/log/list.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/task/retry-failed.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/task/run/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/task/run/list.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/task/run/retry.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/task/update.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/telegrafs/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/telegrafs/create.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/telegrafs/rm.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/telegrafs/update.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/template/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/template/validate.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/transpile/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/user/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/user/create.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/user/delete.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/user/list.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/user/password.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/user/update.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/v1/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/v1/auth/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/v1/auth/create.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/v1/auth/delete.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/v1/auth/list.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/v1/auth/set-active.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/v1/auth/set-inactive.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/v1/auth/set-password.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/v1/dbrp/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/v1/dbrp/create.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/v1/dbrp/delete.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/v1/dbrp/list.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/v1/dbrp/update.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/version/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/write/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influx/write/dryrun.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/downgrade.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/inspect/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/inspect/build-tsi.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/inspect/delete-tsm.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/inspect/dump-tsi.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/inspect/dump-tsm.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/inspect/dump-wal.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/inspect/export-index.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/inspect/export-lp.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/inspect/report-tsi.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/inspect/report-tsm.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/inspect/verify-seriesfile.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/inspect/verify-tombstone.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/inspect/verify-tsm.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/inspect/verify-wal.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/print-config.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/recovery/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/recovery/auth/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/recovery/auth/create-operator.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/recovery/auth/list.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/recovery/org/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/recovery/org/create.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/recovery/org/list.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/recovery/user/_index.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/recovery/user/create.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/recovery/user/list.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/run.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/upgrade.md create mode 100644 content/influxdb/v2.1/reference/cli/influxd/version.md create mode 100644 content/influxdb/v2.1/reference/config-options.md create mode 100644 content/influxdb/v2.1/reference/contributing/_index.md create mode 100644 content/influxdb/v2.1/reference/glossary.md create mode 100644 content/influxdb/v2.1/reference/internals/_index.md create mode 100644 content/influxdb/v2.1/reference/internals/file-system-layout.md create mode 100644 content/influxdb/v2.1/reference/internals/shards.md create mode 100644 content/influxdb/v2.1/reference/internals/storage-engine.md create mode 100644 content/influxdb/v2.1/reference/internals/system-buckets.md create mode 100644 content/influxdb/v2.1/reference/key-concepts/_index.md create mode 100644 content/influxdb/v2.1/reference/key-concepts/data-elements.md create mode 100644 content/influxdb/v2.1/reference/key-concepts/data-schema.md create mode 100644 content/influxdb/v2.1/reference/key-concepts/design-principles.md create mode 100644 content/influxdb/v2.1/reference/prometheus-metrics.md create mode 100644 content/influxdb/v2.1/reference/release-notes/_index.md create mode 100644 content/influxdb/v2.1/reference/release-notes/influx-cli.md create mode 100644 content/influxdb/v2.1/reference/release-notes/influxdb.md create mode 100644 content/influxdb/v2.1/reference/release-notes/supported-release.md create mode 100644 content/influxdb/v2.1/reference/sample-data.md create mode 100644 content/influxdb/v2.1/reference/syntax/_index.md create mode 100644 content/influxdb/v2.1/reference/syntax/annotated-csv/_index.md create mode 100644 content/influxdb/v2.1/reference/syntax/annotated-csv/extended.md create mode 100644 content/influxdb/v2.1/reference/syntax/delete-predicate.md create mode 100644 content/influxdb/v2.1/reference/syntax/flux/_index.md create mode 100644 content/influxdb/v2.1/reference/syntax/flux/flux-vs-influxql.md create mode 100644 content/influxdb/v2.1/reference/syntax/line-protocol.md create mode 100644 content/influxdb/v2.1/reference/telegraf-plugins.md create mode 100644 content/influxdb/v2.1/reference/urls.md create mode 100644 content/influxdb/v2.1/security/_index.md create mode 100644 content/influxdb/v2.1/security/enable-tls.md create mode 100644 content/influxdb/v2.1/security/secrets/_index.md create mode 100644 content/influxdb/v2.1/security/secrets/add.md create mode 100644 content/influxdb/v2.1/security/secrets/delete.md create mode 100644 content/influxdb/v2.1/security/secrets/update.md create mode 100644 content/influxdb/v2.1/security/secrets/use-vault.md create mode 100644 content/influxdb/v2.1/security/secrets/use.md create mode 100644 content/influxdb/v2.1/security/secrets/view.md create mode 100644 content/influxdb/v2.1/security/tokens/_index.md create mode 100644 content/influxdb/v2.1/security/tokens/create-token.md create mode 100644 content/influxdb/v2.1/security/tokens/delete-token.md create mode 100644 content/influxdb/v2.1/security/tokens/update-tokens.md create mode 100644 content/influxdb/v2.1/security/tokens/use-tokens.md create mode 100644 content/influxdb/v2.1/security/tokens/view-tokens.md create mode 100644 content/influxdb/v2.1/tags/_index.md create mode 100644 content/influxdb/v2.1/telegraf-configs/_index.md create mode 100644 content/influxdb/v2.1/telegraf-configs/clone.md create mode 100644 content/influxdb/v2.1/telegraf-configs/create.md create mode 100644 content/influxdb/v2.1/telegraf-configs/remove.md create mode 100644 content/influxdb/v2.1/telegraf-configs/update.md create mode 100644 content/influxdb/v2.1/telegraf-configs/view.md create mode 100644 content/influxdb/v2.1/tools/_index.md create mode 100644 content/influxdb/v2.1/tools/chronograf.md create mode 100644 content/influxdb/v2.1/tools/flux-vim-lsp.md create mode 100644 content/influxdb/v2.1/tools/flux-vscode.md create mode 100644 content/influxdb/v2.1/tools/google-data-studio.md create mode 100644 content/influxdb/v2.1/tools/grafana.md create mode 100644 content/influxdb/v2.1/tools/influx-cli.md create mode 100644 content/influxdb/v2.1/tools/kapacitor.md create mode 100644 content/influxdb/v2.1/tools/repl.md create mode 100644 content/influxdb/v2.1/upgrade/_index.md create mode 100644 content/influxdb/v2.1/upgrade/downgrade.md create mode 100644 content/influxdb/v2.1/upgrade/v1-to-v2/_index.md create mode 100644 content/influxdb/v2.1/upgrade/v1-to-v2/automatic-upgrade.md create mode 100644 content/influxdb/v2.1/upgrade/v1-to-v2/docker.md create mode 100644 content/influxdb/v2.1/upgrade/v1-to-v2/manual-upgrade.md create mode 100644 content/influxdb/v2.1/upgrade/v1-to-v2/migrate-cqs.md create mode 100644 content/influxdb/v2.1/upgrade/v2-to-v2.md create mode 100644 content/influxdb/v2.1/users/_index.md create mode 100644 content/influxdb/v2.1/users/change-password.md create mode 100644 content/influxdb/v2.1/users/create-user.md create mode 100644 content/influxdb/v2.1/users/delete-user.md create mode 100644 content/influxdb/v2.1/users/update-user.md create mode 100644 content/influxdb/v2.1/users/view-users.md create mode 100644 content/influxdb/v2.1/visualize-data/_index.md create mode 100644 content/influxdb/v2.1/visualize-data/annotations.md create mode 100644 content/influxdb/v2.1/visualize-data/dashboards/_index.md create mode 100644 content/influxdb/v2.1/visualize-data/dashboards/control-dashboard.md create mode 100644 content/influxdb/v2.1/visualize-data/dashboards/create-dashboard.md create mode 100644 content/influxdb/v2.1/visualize-data/dashboards/delete-dashboard.md create mode 100644 content/influxdb/v2.1/visualize-data/dashboards/export-dashboard.md create mode 100644 content/influxdb/v2.1/visualize-data/labels.md create mode 100644 content/influxdb/v2.1/visualize-data/variables/_index.md create mode 100644 content/influxdb/v2.1/visualize-data/variables/common-variables.md create mode 100644 content/influxdb/v2.1/visualize-data/variables/create-variable.md create mode 100644 content/influxdb/v2.1/visualize-data/variables/delete-variable.md create mode 100644 content/influxdb/v2.1/visualize-data/variables/export-variable.md create mode 100644 content/influxdb/v2.1/visualize-data/variables/update-variable.md create mode 100644 content/influxdb/v2.1/visualize-data/variables/variable-types.md create mode 100644 content/influxdb/v2.1/visualize-data/variables/view-variables.md create mode 100644 content/influxdb/v2.1/visualize-data/visualization-types/_index.md create mode 100644 content/influxdb/v2.1/visualize-data/visualization-types/band.md create mode 100644 content/influxdb/v2.1/visualize-data/visualization-types/gauge.md create mode 100644 content/influxdb/v2.1/visualize-data/visualization-types/graph-single-stat.md create mode 100644 content/influxdb/v2.1/visualize-data/visualization-types/graph.md create mode 100644 content/influxdb/v2.1/visualize-data/visualization-types/heatmap.md create mode 100644 content/influxdb/v2.1/visualize-data/visualization-types/histogram.md create mode 100644 content/influxdb/v2.1/visualize-data/visualization-types/mosaic.md create mode 100644 content/influxdb/v2.1/visualize-data/visualization-types/scatter.md create mode 100644 content/influxdb/v2.1/visualize-data/visualization-types/single-stat.md create mode 100644 content/influxdb/v2.1/visualize-data/visualization-types/table.md create mode 100644 content/influxdb/v2.1/write-data/_index.md create mode 100644 content/influxdb/v2.1/write-data/best-practices/_index.md create mode 100644 content/influxdb/v2.1/write-data/best-practices/duplicate-points.md create mode 100644 content/influxdb/v2.1/write-data/best-practices/optimize-writes.md create mode 100644 content/influxdb/v2.1/write-data/best-practices/resolve-high-cardinality.md create mode 100644 content/influxdb/v2.1/write-data/best-practices/schema-design.md create mode 100644 content/influxdb/v2.1/write-data/delete-data.md create mode 100644 content/influxdb/v2.1/write-data/developer-tools/_index.md create mode 100644 content/influxdb/v2.1/write-data/developer-tools/api.md create mode 100644 content/influxdb/v2.1/write-data/developer-tools/client-libraries.md create mode 100644 content/influxdb/v2.1/write-data/developer-tools/csv.md create mode 100644 content/influxdb/v2.1/write-data/developer-tools/influx-cli.md create mode 100644 content/influxdb/v2.1/write-data/developer-tools/scrape-prometheus-metrics.md create mode 100644 content/influxdb/v2.1/write-data/developer-tools/third-party-solutions.md create mode 100644 content/influxdb/v2.1/write-data/no-code/_index.md create mode 100644 content/influxdb/v2.1/write-data/no-code/load-data.md create mode 100644 content/influxdb/v2.1/write-data/no-code/scrape-data/_index.md create mode 100644 content/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/_index.md create mode 100644 content/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/create-a-scraper.md create mode 100644 content/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/delete-a-scraper.md create mode 100644 content/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/update-a-scraper.md create mode 100644 content/influxdb/v2.1/write-data/no-code/scrape-data/scrapable-endpoints.md create mode 100644 content/influxdb/v2.1/write-data/no-code/third-party.md create mode 100644 content/influxdb/v2.1/write-data/no-code/use-telegraf/_index.md create mode 100644 content/influxdb/v2.1/write-data/no-code/use-telegraf/auto-config.md create mode 100644 content/influxdb/v2.1/write-data/no-code/use-telegraf/manual-config.md create mode 100644 content/influxdb/v2.1/write-data/no-code/use-telegraf/use-telegraf-plugins/_index.md create mode 100644 content/influxdb/v2.1/write-data/no-code/use-telegraf/use-telegraf-plugins/use-http-plugin.md create mode 100644 content/influxdb/v2.1/write-data/troubleshoot.md create mode 100644 data/influxd_flags.yml create mode 100644 layouts/partials/article/page-meta.html create mode 100644 layouts/shortcodes/caps.html create mode 100644 layouts/shortcodes/cli/influxd-flags.html delete mode 100644 layouts/shortcodes/cli/influxd-flags.md create mode 100644 layouts/shortcodes/current-version.html create mode 100644 layouts/shortcodes/influxdb/install-old-versions.html create mode 100644 shared/text/api/v1-compat/auth/cloud/querystring-auth.js create mode 100644 shared/text/api/v1-compat/auth/cloud/querystring-auth.sh create mode 100644 static/fonts/icomoon-v2.eot create mode 100644 static/fonts/icomoon-v2.svg create mode 100644 static/fonts/icomoon-v2.ttf create mode 100644 static/fonts/icomoon-v2.woff create mode 100644 static/fonts/icomoon.woff2 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c0bb21124b..6dbf69a291 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -94,6 +94,8 @@ prepend: # Prepend markdown content to an article (especially powerful with casc append: # Append markdown content to an article (especially powerful with cascade) block: # (Optional) Wrap content in a block style (note, warn, cloud) content: # Content to append to article +metadata: [] # List of metadata messages to include under the page h1 +updated_in: # Product and version the referenced feature was updated in (displayed as a unique metadata) ``` ### Title usage @@ -818,9 +820,11 @@ The following table shows which children types use which frontmatter properties: ### Inline icons The `icon` shortcode allows you to inject icons in paragraph text. It's meant to clarify references to specific elements in the InfluxDB user interface. +This shortcode supports clockface (the UI) v2 and v3. +Specify the version to use as the 2nd argument. The default version is `v3`. ``` -{{< icon "icon-name" >}} +{{< icon "icon-name" "v2" >}} ``` Below is a list of available icons (some are aliases): @@ -890,9 +894,11 @@ Below is a list of available icons (some are aliases): ### InfluxDB UI left navigation icons In many cases, documentation references an item in the left nav of the InfluxDB UI. Provide a visual example of the navigation item using the `nav-icon` shortcode. +This shortcode supports clockface (the UI) v2 and v3. +Specify the version to use as the 2nd argument. The default version is `v3`. ``` -{{< nav-icon "tasks" >}} +{{< nav-icon "tasks" "v2" >}} ``` The following case insensitive values are supported: @@ -1048,6 +1054,14 @@ This is necessary to get the first sentence/paragraph to render correctly. {{% /cloud-only %}} ``` +#### All-Caps +Clockface v3 introduces many buttons with text formatted as all-caps. +Use the `{{< caps >}}` shortcode to format text to match those buttons. + +```md +Click {{< caps >}}Add Data{{< /caps >}} +``` + ### Reference content The InfluxDB documentation is "task-based," meaning content primarily focuses on what a user is **doing**, not what they are **using**. diff --git a/api-docs/cloud/ref.yml b/api-docs/cloud/ref.yml index 46da8d26d7..3b9fa93cc3 100644 --- a/api-docs/cloud/ref.yml +++ b/api-docs/cloud/ref.yml @@ -5886,31 +5886,37 @@ components: type: object securitySchemes: BasicAuthentication: - type: http - scheme: basic description: > ### Basic authentication scheme - Use HTTP Basic Auth with clients that support the InfluxDB 1.x - convention of username and password (that don't support the + Use the HTTP Basic authentication scheme with clients that support the + InfluxDB 1.x convention of username and password (that don't support the `Authorization: Token` scheme): - **username**: InfluxDB Cloud username - **password**: InfluxDB Cloud API token - ### Example + #### Example `curl --get "https://europe-west1-1.gcp.cloud2.influxdata.com/query" - --user "YOUR_USERNAME":"YOUR_TOKEN_OR_PASSWORD"` + --user "exampleuser@influxdata.com":"INFLUX_API_TOKEN"` + + Replace the following: + + - *`exampleuser@influxdata.com`*: the email address that you signed up + with + + - *`INFLUX_API_TOKEN`*: your [InfluxDB API + token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) + For more information and examples, see how to [authenticate with a - username and password - scheme](https://docs.influxdata.com/influxdb/cloud/reference/api/influxdb-1x/). + username and + password](https://docs.influxdata.com/influxdb/cloud/reference/api/influxdb-1x/). + scheme: basic + type: http QuerystringAuthentication: - type: apiKey - in: query - name: u=&p= description: > ### Querystring authentication scheme @@ -5926,20 +5932,30 @@ components: - **password**: InfluxDB Cloud API token - ### Example + #### Example `curl --get "https://europe-west1-1.gcp.cloud2.influxdata.com/query" - --data-urlencode "u=YOUR_USERNAME" - --data-urlencode "p=YOUR_TOKEN_OR_PASSWORD"` + --data-urlencode "u=exampleuser@influxdata.com" + --data-urlencode "p=INFLUX_API_TOKEN"` + + Replace the following: + + - *`exampleuser@influxdata.com`*: the email address that you signed up + with + + - *`INFLUX_API_TOKEN`*: your [InfluxDB API + token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) + For more information and examples, see how to [authenticate with a username and password scheme](https://docs.influxdata.com/influxdb/cloud/reference/api/influxdb-1x/). + in: query + name: u=&p= + type: apiKey TokenAuthentication: - type: http - scheme: token - bearerFormat: InfluxDB Token String + bearerFormat: InfluxDB token string description: > ### Token authentication scheme @@ -5949,20 +5965,27 @@ components: within the organization. - Include your API token in an `Authorization: Token YOUR_API_TOKEN` HTTP + Include your API token in an `Authorization: Token INFLUX_TOKEN` HTTP header with each request. - ### Example + #### Example `curl https://us-east-1-1.aws.cloud2.influxdata.com/ - --header "Authorization: Token YOUR_API_TOKEN"` + --header "Authorization: Token INFLUX_API_TOKEN"` + + Replace *`INFLUX_API_TOKEN`* with your [InfluxDB API + token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token). + For more information and examples, see the following: + - [`/authorizations`](#tag/Authorizations) endpoint. - [Use tokens in API requests](https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/#authentication). - [Manage API tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens). - - [`/authorizations`](#tag/Authorizations) endpoint. + - [Assign a token to a specific user](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token). + scheme: token + type: http info: title: Influx Cloud API Service description: > @@ -12326,8 +12349,7 @@ security: servers: - url: / tags: - - name: Authentication - description: > + - description: > Use one of the following schemes to authenticate to the InfluxDB API: - [Token authentication](#section/Authentication/TokenAuthentication) @@ -12338,12 +12360,20 @@ tags: authentication](#section/Authentication/QuerystringAuthentication) + name: Authentication x-traitTag: true - - name: Authorizations - description: > + - description: > Create and manage API tokens. An **authorization** associates a list of - permissions to an **organization** and provides a token for API access. To - assign a token to a specific user, scope the authorization to the user ID. + permissions to an **organization** and provides a token for API access. + Optionally, you can restrict an authorization and its token to a specific + user. + + + For more information and examples, see the following: + - [Use tokens in API requests](https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/#authentication). + - [Manage API tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens). + - [Assign a token to a specific user](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token). + name: Authorizations - Bucket Schemas - Buckets - Cells @@ -12352,45 +12382,17 @@ tags: - DBRPs - Delete - DemoDataBuckets - - name: Invocable Scripts - description: > - Manage and execute scripts as API endpoints in InfluxDB. - - - An API Invocable Script assigns your custom Flux script to a new InfluxDB - API endpoint for your organization. - - Invocable scripts let you execute your script as an HTTP request to the - endpoint. - - - Invocable scripts accept parameters. Add parameter references in your - script as `params.myparameter`. - - When you `invoke` your script, you send parameters as key-value pairs in - the `params` object. - - InfluxDB executes your script with the key-value pairs as arguments and - returns the result. - - - For more information and examples, see [Invoke custom - scripts](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invocable-scripts). + - Invocable Scripts - Labels - Limits - NotificationEndpoints - NotificationRules - Organizations - Ping - - name: Query - description: | + - description: | Retrieve data, analyze queries, and get query suggestions. - - name: Quick start - description: Some quickness - x-traitTag: true - - name: Quick start - x-traitTag: true - description: > + name: Query + - description: > See the [**API Quick Start**](https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/) to get up and running authenticating with tokens, writing to buckets, and @@ -12401,10 +12403,10 @@ tags: libraries**](https://docs.influxdata.com/influxdb/cloud/api-guide/client-libraries/) are available for popular languages and ready to import into your application. - - Resources - - name: Response codes + name: Quick start x-traitTag: true - description: > + - Resources + - description: > The InfluxDB API uses standard HTTP status codes for success and failure responses. @@ -12457,6 +12459,8 @@ tags: | `503` | Service unavailable | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. | + name: Response codes + x-traitTag: true - Routes - Rules - Secrets @@ -12471,9 +12475,9 @@ tags: - Users - Variables - Views - - name: Write - description: | + - description: | Write time series data to buckets. + name: Write x-tagGroups: - name: Overview tags: diff --git a/api-docs/openapi/content/cloud/tags.yml b/api-docs/openapi/content/cloud/tags.yml index 18cd6f263e..0304eda51b 100644 --- a/api-docs/openapi/content/cloud/tags.yml +++ b/api-docs/openapi/content/cloud/tags.yml @@ -1,6 +1,3 @@ -- name: Quick start - description: Some quickness - x-traitTag: true - name: Authentication description: | Use one of the following schemes to authenticate to the InfluxDB API: @@ -18,7 +15,7 @@ Invocable scripts accept parameters. Add parameter references in your script as `params.myparameter`. When you `invoke` your script, you send parameters as key-value pairs in the `params` object. - InfluxDB executes your script with the key-value pairs as arguments and returns the result. + Then, InfluxDB executes your script with the key-value pairs as arguments, and returns the result. For more information and examples, see [Invoke custom scripts](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invocable-scripts). - name: Quick start diff --git a/api-docs/openapi/content/v2.1/info.yml b/api-docs/openapi/content/v2.1/info.yml new file mode 100644 index 0000000000..48eb41eae0 --- /dev/null +++ b/api-docs/openapi/content/v2.1/info.yml @@ -0,0 +1,3 @@ +title: Influx OSS API Service +description: | + The InfluxDB v2 API provides a programmatic interface for all interactions with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint. diff --git a/api-docs/openapi/content/v2.1/security-schemes.yml b/api-docs/openapi/content/v2.1/security-schemes.yml new file mode 100644 index 0000000000..c12659c01d --- /dev/null +++ b/api-docs/openapi/content/v2.1/security-schemes.yml @@ -0,0 +1,58 @@ +TokenAuthentication: + type: http + scheme: token + bearerFormat: InfluxDB Token String + description: | + ### Token authentication scheme + + InfluxDB API tokens ensure secure interaction between users and data. A token belongs to an organization and identifies InfluxDB permissions within the organization. + + Include your API token in an `Authentication: Token YOUR_API_TOKEN` HTTP header with each request. + + ### Example + + `curl http://localhost:8086/ping + --header "Authentication: Token YOUR_API_TOKEN"` + + For more information and examples, see the following: + - [Use tokens in API requests](https://docs.influxdata.com/influxdb/v2.1/api-guide/api_intro/#authentication). + - [Manage API tokens](https://docs.influxdata.com/influxdb/v2.1/security/tokens). + - [`/authorizations`](#tag/Authorizations) endpoint. +BasicAuthentication: + type: http + scheme: basic + description: | + ### Basic authentication scheme + + Use HTTP Basic Auth with clients that support the InfluxDB 1.x convention of username and password (that don't support the `Authorization: Token` scheme). + + Username and password schemes require the following credentials: + - **username**: 1.x username (this is separate from the UI login username) + - **password**: 1.x password or InfluxDB API token + + ### Example + + `curl --get "http://localhost:8086/query" + --user "YOUR_1.x_USERNAME":"YOUR_TOKEN_OR_PASSWORD"` + + For more information and examples, see how to [authenticate with a username and password scheme](https://docs.influxdata.com/influxdb/v2.1/reference/api/influxdb-1x/) +QuerystringAuthentication: + type: apiKey + in: query + name: u=&p= + description: | + ### Querystring authentication scheme + + Use InfluxDB 1.x API parameters to provide credentials through the query string. + + Username and password schemes require the following credentials: + - **username**: 1.x username (this is separate from the UI login username) + - **password**: 1.x password or InfluxDB API token + + ### Example + + `curl --get "http://localhost:8086/query" + --data-urlencode "u=YOUR_1.x_USERNAME" + --data-urlencode "p=YOUR_TOKEN_OR_PASSWORD"` + + For more information and examples, see how to [authenticate with a username and password scheme](https://docs.influxdata.com/influxdb/v2.1/reference/api/influxdb-1x/) diff --git a/api-docs/openapi/content/v2.1/tag-groups.yml b/api-docs/openapi/content/v2.1/tag-groups.yml new file mode 100644 index 0000000000..da30ad6922 --- /dev/null +++ b/api-docs/openapi/content/v2.1/tag-groups.yml @@ -0,0 +1,28 @@ +- name: Overview + tags: + - Quick start + - Authentication + - Response codes +- name: Data I/O endpoints + tags: + - Write + - Query +- name: Resource endpoints + tags: + - Buckets + - Dashboards + - Tasks + - Resources +- name: Security and access endpoints + tags: + - Authorizations + - Organizations + - Users +- name: System information endpoints + tags: + - Health + - Ping + - Ready + - Routes +- name: All endpoints + tags: [] diff --git a/api-docs/openapi/content/v2.1/tags.yml b/api-docs/openapi/content/v2.1/tags.yml new file mode 100644 index 0000000000..7659f4e772 --- /dev/null +++ b/api-docs/openapi/content/v2.1/tags.yml @@ -0,0 +1,43 @@ +- name: Authentication + description: | + Use one of the following schemes to authenticate to the InfluxDB API: + - [Token authentication](#section/Authentication/TokenAuthentication) + - [Basic authentication](#section/Authentication/BasicAuthentication) + - [Querystring authentication](#section/Authentication/QuerystringAuthentication) + + x-traitTag: true +- name: Quick start + x-traitTag: true + description: | + See the [**API Quick Start**](https://docs.influxdata.com/influxdb/v2.1/api-guide/api_intro/) to get up and running authenticating with tokens, writing to buckets, and querying data. + + [**InfluxDB API client libraries**](https://docs.influxdata.com/influxdb/v2.1/api-guide/client-libraries/) are available for popular languages and ready to import into your application. +- name: Response codes + x-traitTag: true + description: | + The InfluxDB API uses standard HTTP status codes for success and failure responses. + The response body may include additional details. For details about a specific operation's response, see **Responses** and **Response Samples** for that operation. + + API operations may return the following HTTP status codes: + + |  Code  | Status | Description | + |:-----------:|:------------------------ |:--------------------- | + | `200` | Success | | + | `204` | No content | For a `POST` request, `204` indicates that InfluxDB accepted the request and request data is valid. Asynchronous operations, such as `write`, might not have completed yet. | + | `400` | Bad request | `Authorization` header is missing or malformed or the API token does not have permission for the operation. | + | `401` | Unauthorized | May indicate one of the following:
  • `Authorization: Token` header is missing or malformed
  • API token value is missing from the header
  • API token does not have permission. For more information about token types and permissions, see [Manage API tokens](https://docs.influxdata.com/influxdb/v2.1/security/tokens/)
    • | + | `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. | + | `413` | Request entity too large | Request payload exceeds the size limit. | + | `422` | Unprocessible entity | Request data is invalid. `code` and `message` in the response body provide details about the problem. | + | `429` | Too many requests | API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again. | + | `500` | Internal server error | | + | `503` | Service unavailable | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. | +- name: Query + description: | + Retrieve data, analyze queries, and get query suggestions. +- name: Write + description: | + Write time series data to buckets. +- name: Authorizations + description: | + Create and manage API tokens. An **authorization** associates a list of permissions to an **organization** and provides a token for API access. To assign a token to a specific user, scope the authorization to the user ID. diff --git a/api-docs/openapi/plugins/docs-plugin.js b/api-docs/openapi/plugins/docs-plugin.js index 75492c3f1b..a54baa1b92 100644 --- a/api-docs/openapi/plugins/docs-plugin.js +++ b/api-docs/openapi/plugins/docs-plugin.js @@ -46,8 +46,6 @@ module.exports = { 'docs/remove-private-paths': 'error', 'docs/strip-version-prefix': 'error', 'docs/set-info': 'error', - 'docs/set-security-schemes': 'error', - 'docs/set-tags': 'error', 'docs/set-tag-groups': 'error', }, }, diff --git a/api-docs/v2.0/ref.yml b/api-docs/v2.0/ref.yml index 0ccea0e356..6f4cdf58ce 100644 --- a/api-docs/v2.0/ref.yml +++ b/api-docs/v2.0/ref.yml @@ -1,7535 +1,3 @@ -openapi: 3.0.0 -info: - title: Influx OSS API Service - version: 2.0.0 - description: > - The InfluxDB v2 API provides a programmatic interface for all interactions - with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint. -servers: - - url: / -tags: - - name: Authentication - description: > - Use one of the following schemes to authenticate to the InfluxDB API: - - - [Token authentication](#section/Authentication/TokenAuthentication) - - - [Basic authentication](#section/Authentication/BasicAuthentication) - - - [Querystring - authentication](#section/Authentication/QuerystringAuthentication) - - - x-traitTag: true - - name: Authorizations - description: > - Create and manage API tokens. An **authorization** associates a list of - permissions to an **organization** and provides a token for API access. To - assign a token to a specific user, scope the authorization to the user ID. - - Backup - - Buckets - - Cells - - Checks - - Dashboards - - DBRPs - - Delete - - Health - - Labels - - Legacy Authorizations - - NotificationEndpoints - - NotificationRules - - Organizations - - Ping - - name: Query - description: | - Retrieve data, analyze queries, and get query suggestions. - - name: Quick start - x-traitTag: true - description: > - See the [**API Quick - Start**](https://docs.influxdata.com/influxdb/v2.0/api-guide/api_intro/) - to get up and running authenticating with tokens, writing to buckets, and - querying data. - - - [**InfluxDB API client - libraries**](https://docs.influxdata.com/influxdb/v2.0/api-guide/client-libraries/) - are available for popular languages and ready to import into your - application. - - Ready - - RemoteConnections - - Replications - - Resources - - name: Response codes - x-traitTag: true - description: > - The InfluxDB API uses standard HTTP status codes for success and failure - responses. - - The response body may include additional details. For details about a - specific operation's response, see **Responses** and **Response Samples** - for that operation. - - - API operations may return the following HTTP status codes: - - - |  Code  | Status | Description | - - |:-----------:|:------------------------ |:--------------------- | - - | `200` | Success | | - - | `204` | No content | For a `POST` request, `204` - indicates that InfluxDB accepted the request and request data is valid. - Asynchronous operations, such as `write`, might not have completed yet. | - - | `400` | Bad request | `Authorization` header is - missing or malformed or the API token does not have permission for the - operation. | - - | `401` | Unauthorized | May indicate one of the - following:
  • `Authorization: Token` header is missing or - malformed
  • API token value is missing from the header
  • API - token does not have permission. For more information about token types and - permissions, see [Manage API - tokens](https://docs.influxdata.com/influxdb/v2.0/security/tokens/)
    • | - - | `404` | Not found | Requested resource was not - found. `message` in the response body provides details about the requested - resource. | - - | `413` | Request entity too large | Request payload exceeds the - size limit. | - - | `422` | Unprocessible entity | Request data is invalid. `code` - and `message` in the response body provide details about the problem. | - - | `429` | Too many requests | API token is temporarily over - the request quota. The `Retry-After` header describes when to try the - request again. | - - | `500` | Internal server error | | - - | `503` | Service unavailable | Server is temporarily - unavailable to process the request. The `Retry-After` header describes - when to try the request again. | - - Restore - - Routes - - Rules - - Scraper Targets - - Secrets - - Setup - - Signin - - Signout - - Sources - - Tasks - - Telegraf Plugins - - Telegrafs - - Templates - - Users - - Variables - - Views - - name: Write - description: | - Write time series data to buckets. -x-tagGroups: - - name: Overview - tags: - - Quick start - - Authentication - - Response codes - - name: Data I/O endpoints - tags: - - Write - - Query - - name: Resource endpoints - tags: - - Buckets - - Dashboards - - Tasks - - Resources - - name: Security and access endpoints - tags: - - Authorizations - - Organizations - - Users - - name: System information endpoints - tags: - - Health - - Ping - - Ready - - Routes - - name: All endpoints - tags: - - Authorizations - - Backup - - Buckets - - Cells - - Checks - - Dashboards - - DBRPs - - Delete - - Health - - Labels - - Legacy Authorizations - - NotificationEndpoints - - NotificationRules - - Organizations - - Ping - - Query - - Ready - - RemoteConnections - - Replications - - Resources - - Restore - - Routes - - Rules - - Scraper Targets - - Secrets - - Setup - - Signin - - Signout - - Sources - - Tasks - - Telegraf Plugins - - Telegrafs - - Templates - - Users - - Variables - - Views - - Write -paths: - /api/v2/: - get: - operationId: GetRoutes - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Routes' - description: All routes - summary: List all top level routes - tags: - - Routes - servers: - - url: / - /api/v2/authorizations: - get: - operationId: GetAuthorizations - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: Only show authorizations that belong to a user ID. - in: query - name: userID - schema: - type: string - - description: Only show authorizations that belong to a user name. - in: query - name: user - schema: - type: string - - description: Only show authorizations that belong to an organization ID. - in: query - name: orgID - schema: - type: string - - description: Only show authorizations that belong to a organization name. - in: query - name: org - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorizations' - description: A list of authorizations - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: List all authorizations - tags: - - Authorizations - post: - operationId: PostAuthorizations - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationPostRequest' - description: Authorization to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: Authorization created - '400': - $ref: '#/components/responses/ServerError' - description: Invalid request - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Create an authorization - tags: - - Authorizations - /api/v2/authorizations/{authID}: - delete: - operationId: DeleteAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the authorization to delete. - in: path - name: authID - required: true - schema: - type: string - responses: - '204': - description: Authorization deleted - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Delete an authorization - tags: - - Authorizations - get: - operationId: GetAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the authorization to get. - in: path - name: authID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: Authorization details - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Retrieve an authorization - tags: - - Authorizations - patch: - operationId: PatchAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the authorization to update. - in: path - name: authID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - description: Authorization to update - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: The active or inactive authorization - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Update an authorization to be active or inactive - tags: - - Authorizations - /api/v2/backup/kv: - get: - deprecated: true - operationId: GetBackupKV - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/octet-stream: - schema: - format: binary - type: string - description: Snapshot of KV metadata - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: >- - Download snapshot of metadata stored in the server's embedded KV store. - Should not be used in versions greater than 2.1.x, as it doesn't include - metadata stored in embedded SQL. - tags: - - Backup - /api/v2/backup/metadata: - get: - operationId: GetBackupMetadata - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: >- - The Accept-Encoding request HTTP header advertises which content - encoding, usually a compression algorithm, the client is able to - understand. - in: header - name: Accept-Encoding - schema: - default: identity - description: >- - Specifies that the query response in the body should be encoded - with gzip or not encoded with identity. - enum: - - gzip - - identity - type: string - responses: - '200': - content: - multipart/mixed: - schema: - $ref: '#/components/schemas/MetadataBackup' - description: Snapshot of metadata - headers: - Content-Encoding: - description: >- - The Content-Encoding entity header is used to compress the - media-type. When present, its value indicates which encodings - were applied to the entity-body - schema: - default: identity - description: >- - Specifies that the response in the body is encoded with gzip - or not encoded with identity. - enum: - - gzip - - identity - type: string - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Download snapshot of all metadata in the server - tags: - - Backup - /api/v2/backup/shards/{shardID}: - get: - operationId: GetBackupShardId - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: >- - The Accept-Encoding request HTTP header advertises which content - encoding, usually a compression algorithm, the client is able to - understand. - in: header - name: Accept-Encoding - schema: - default: identity - description: >- - Specifies that the query response in the body should be encoded - with gzip or not encoded with identity. - enum: - - gzip - - identity - type: string - - description: The shard ID. - in: path - name: shardID - required: true - schema: - format: int64 - type: integer - - description: Earliest time to include in the snapshot. RFC3339 format. - in: query - name: since - schema: - format: date-time - type: string - responses: - '200': - content: - application/octet-stream: - schema: - format: binary - type: string - description: TSM snapshot. - headers: - Content-Encoding: - description: >- - The Content-Encoding entity header is used to compress the - media-type. When present, its value indicates which encodings - were applied to the entity-body - schema: - default: identity - description: >- - Specifies that the response in the body is encoded with gzip - or not encoded with identity. - enum: - - gzip - - identity - type: string - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Shard not found. - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Download snapshot of all TSM data in a shard - tags: - - Backup - /api/v2/buckets: - get: - operationId: GetBuckets - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - $ref: '#/components/parameters/After' - - description: The name of the organization. - in: query - name: org - schema: - type: string - - description: The organization ID. - in: query - name: orgID - schema: - type: string - - description: Only returns buckets with a specific name. - in: query - name: name - schema: - type: string - - description: Only returns buckets with a specific ID. - in: query - name: id - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Buckets' - description: A list of buckets - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all buckets - tags: - - Buckets - post: - operationId: PostBuckets - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PostBucketRequest' - description: Bucket to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Bucket' - description: Bucket created - '422': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Request body failed validation - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a bucket - tags: - - Buckets - /api/v2/buckets/{bucketID}: - delete: - operationId: DeleteBucketsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the bucket to delete. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Bucket not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a bucket - tags: - - Buckets - get: - operationId: GetBucketsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Bucket' - description: Bucket details - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a bucket - tags: - - Buckets - patch: - operationId: PatchBucketsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. - in: path - name: bucketID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PatchBucketRequest' - description: Bucket update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Bucket' - description: An updated bucket - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a bucket - tags: - - Buckets - /api/v2/buckets/{bucketID}/labels: - get: - operationId: GetBucketsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a bucket - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a bucket - tags: - - Buckets - post: - operationId: PostBucketsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. - in: path - name: bucketID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The newly added label - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a bucket - tags: - - Buckets - /api/v2/buckets/{bucketID}/labels/{labelID}: - delete: - operationId: DeleteBucketsIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. - in: path - name: bucketID - required: true - schema: - type: string - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Bucket not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a bucket - tags: - - Buckets - /api/v2/buckets/{bucketID}/members: - get: - operationId: GetBucketsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMembers' - description: A list of bucket members - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all users with member privileges for a bucket - tags: - - Buckets - post: - operationId: PostBucketsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. - in: path - name: bucketID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as member - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMember' - description: Member added to bucket - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to a bucket - tags: - - Buckets - /api/v2/buckets/{bucketID}/members/{userID}: - delete: - operationId: DeleteBucketsIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the member to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The bucket ID. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '204': - description: Member removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from a bucket - tags: - - Buckets - /api/v2/buckets/{bucketID}/owners: - get: - operationId: GetBucketsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwners' - description: A list of bucket owners - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all owners of a bucket - tags: - - Buckets - post: - operationId: PostBucketsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. - in: path - name: bucketID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as owner - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwner' - description: Bucket owner added - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add an owner to a bucket - tags: - - Buckets - /api/v2/buckets/{bucketID}/owners/{userID}: - delete: - operationId: DeleteBucketsIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the owner to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The bucket ID. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '204': - description: Owner removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from a bucket - tags: - - Buckets - /api/v2/checks: - get: - operationId: GetChecks - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - description: Only show checks that belong to a specific organization ID. - in: query - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Checks' - description: A list of checks - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all checks - tags: - - Checks - post: - operationId: CreateCheck - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PostCheck' - description: Check to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Check' - description: Check created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add new check - tags: - - Checks - /api/v2/checks/{checkID}: - delete: - operationId: DeleteChecksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The check was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a check - tags: - - Checks - get: - operationId: GetChecksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Check' - description: The check requested - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a check - tags: - - Checks - patch: - operationId: PatchChecksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CheckPatch' - description: Check update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Check' - description: An updated check - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The check was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a check - tags: - - Checks - put: - operationId: PutChecksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Check' - description: Check update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Check' - description: An updated check - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The check was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a check - tags: - - Checks - /api/v2/checks/{checkID}/labels: - get: - operationId: GetChecksIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a check - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a check - tags: - - Checks - post: - operationId: PostChecksIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The label was added to the check - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a check - tags: - - Checks - /api/v2/checks/{checkID}/labels/{labelID}: - delete: - operationId: DeleteChecksIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Check or label not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete label from a check - tags: - - Checks - /api/v2/checks/{checkID}/query: - get: - operationId: GetChecksIDQuery - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/FluxResponse' - description: The check query requested - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Invalid request - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Check not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a check query - tags: - - Checks - /api/v2/dashboards: - get: - operationId: GetDashboards - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - $ref: '#/components/parameters/Descending' - - description: >- - A user identifier. Returns only dashboards where this user has the - `owner` role. - in: query - name: owner - schema: - type: string - - description: The column to sort by. - in: query - name: sortBy - schema: - enum: - - ID - - CreatedAt - - UpdatedAt - type: string - - description: >- - A list of dashboard identifiers. Returns only the listed dashboards. - If both `id` and `owner` are specified, only `id` is used. - in: query - name: id - schema: - items: - type: string - type: array - - description: The identifier of the organization. - in: query - name: orgID - schema: - type: string - - description: The name of the organization. - in: query - name: org - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Dashboards' - description: All dashboards - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all dashboards - tags: - - Dashboards - post: - operationId: PostDashboards - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CreateDashboardRequest' - description: Dashboard to create - required: true - responses: - '201': - content: - application/json: - schema: - oneOf: - - $ref: '#/components/schemas/Dashboard' - - $ref: '#/components/schemas/DashboardWithViewProperties' - description: Added dashboard - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}: - delete: - operationId: DeleteDashboardsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a dashboard - tags: - - Dashboards - get: - operationId: GetDashboardsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - - description: >- - Includes the cell view properties in the response if set to - `properties` - in: query - name: include - required: false - schema: - enum: - - properties - type: string - responses: - '200': - content: - application/json: - schema: - oneOf: - - $ref: '#/components/schemas/Dashboard' - - $ref: '#/components/schemas/DashboardWithViewProperties' - description: Retrieve a single dashboard - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a Dashboard - tags: - - Dashboards - patch: - operationId: PatchDashboardsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - properties: - cells: - $ref: '#/components/schemas/CellWithViewProperties' - description: >- - optional, when provided will replace all existing cells with - the cells provided - description: - description: optional, when provided will replace the description - type: string - name: - description: optional, when provided will replace the name - type: string - title: PatchDashboardRequest - type: object - description: Patching of a dashboard - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Dashboard' - description: Updated dashboard - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/cells: - post: - operationId: PostDashboardsIDCells - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CreateCell' - description: Cell that will be added - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Cell' - description: Cell successfully added - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a dashboard cell - tags: - - Cells - - Dashboards - put: - description: >- - Replaces all cells in a dashboard. This is used primarily to update the - positional information of all cells. - operationId: PutDashboardsIDCells - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Cells' - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Dashboard' - description: Replaced dashboard cells - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Replace cells in a dashboard - tags: - - Cells - - Dashboards - /api/v2/dashboards/{dashboardID}/cells/{cellID}: - delete: - operationId: DeleteDashboardsIDCellsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to delete. - in: path - name: dashboardID - required: true - schema: - type: string - - description: The ID of the cell to delete. - in: path - name: cellID - required: true - schema: - type: string - responses: - '204': - description: Cell successfully deleted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Cell or dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a dashboard cell - tags: - - Cells - - Dashboards - patch: - description: >- - Updates the non positional information related to a cell. Updates to a - single cell's positional data could cause grid conflicts. - operationId: PatchDashboardsIDCellsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - - description: The ID of the cell to update. - in: path - name: cellID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CellUpdate' - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Cell' - description: Updated dashboard cell - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Cell or dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update the non-positional information related to a cell - tags: - - Cells - - Dashboards - /api/v2/dashboards/{dashboardID}/cells/{cellID}/view: - get: - operationId: GetDashboardsIDCellsIDView - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - - description: The cell ID. - in: path - name: cellID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/View' - description: A dashboard cells view - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Cell or dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve the view for a cell - tags: - - Cells - - Dashboards - - Views - patch: - operationId: PatchDashboardsIDCellsIDView - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - - description: The ID of the cell to update. - in: path - name: cellID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/View' - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/View' - description: Updated cell view - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Cell or dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update the view for a cell - tags: - - Cells - - Dashboards - - Views - /api/v2/dashboards/{dashboardID}/labels: - get: - operationId: GetDashboardsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a dashboard - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a dashboard - tags: - - Dashboards - post: - operationId: PostDashboardsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The label added to the dashboard - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/labels/{labelID}: - delete: - operationId: DeleteDashboardsIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/members: - get: - operationId: GetDashboardsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMembers' - description: A list of users who have member privileges for a dashboard - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all dashboard members - tags: - - Dashboards - post: - operationId: PostDashboardsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as member - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMember' - description: Added to dashboard members - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/members/{userID}: - delete: - operationId: DeleteDashboardsIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the member to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '204': - description: Member removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/owners: - get: - operationId: GetDashboardsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwners' - description: A list of users who have owner privileges for a dashboard - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all dashboard owners - tags: - - Dashboards - post: - operationId: PostDashboardsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as owner - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwner' - description: Added to dashboard owners - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add an owner to a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/owners/{userID}: - delete: - operationId: DeleteDashboardsIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the owner to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '204': - description: Owner removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from a dashboard - tags: - - Dashboards - /api/v2/dbrps: - get: - operationId: GetDBRPs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: Specifies the organization ID to filter on - in: query - name: orgID - schema: - type: string - - description: Specifies the organization name to filter on - in: query - name: org - schema: - type: string - - description: Specifies the mapping ID to filter on - in: query - name: id - schema: - type: string - - description: Specifies the bucket ID to filter on - in: query - name: bucketID - schema: - type: string - - description: Specifies filtering on default - in: query - name: default - schema: - type: boolean - - description: Specifies the database to filter on - in: query - name: db - schema: - type: string - - description: Specifies the retention policy to filter on - in: query - name: rp - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/DBRPs' - description: Success. Returns a list of database retention policy mappings. - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Bad request. The request has one or more invalid parameters. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List database retention policy mappings - tags: - - DBRPs - post: - operationId: PostDBRP - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/DBRPCreate' - description: The database retention policy mapping to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/DBRP' - description: Created. Returns the created database retention policy mapping. - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Bad request. The mapping in the request has one or more invalid IDs. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a database retention policy mapping - tags: - - DBRPs - /api/v2/dbrps/{dbrpID}: - delete: - operationId: DeleteDBRPID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: Specifies the organization ID of the mapping - in: query - name: orgID - schema: - type: string - - description: Specifies the organization name of the mapping - in: query - name: org - schema: - type: string - - description: The database retention policy mapping - in: path - name: dbrpID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: if any of the IDs passed is invalid - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a database retention policy - tags: - - DBRPs - get: - operationId: GetDBRPsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: Specifies the organization ID of the mapping - in: query - name: orgID - schema: - type: string - - description: Specifies the organization name of the mapping - in: query - name: org - schema: - type: string - - description: The database retention policy mapping ID - in: path - name: dbrpID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/DBRPGet' - description: The database retention policy requested - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: if any of the IDs passed is invalid - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a database retention policy mapping - tags: - - DBRPs - patch: - operationId: PatchDBRPID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: Specifies the organization ID of the mapping - in: query - name: orgID - schema: - type: string - - description: Specifies the organization name of the mapping - in: query - name: org - schema: - type: string - - description: The database retention policy mapping. - in: path - name: dbrpID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/DBRPUpdate' - description: Database retention policy update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/DBRPGet' - description: An updated mapping - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: if any of the IDs passed is invalid - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The mapping was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a database retention policy mapping - tags: - - DBRPs - /api/v2/delete: - post: - operationId: PostDelete - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: Specifies the organization to delete data from. - in: query - name: org - schema: - description: Only points from this organization are deleted. - type: string - - description: Specifies the bucket to delete data from. - in: query - name: bucket - schema: - description: Only points from this bucket are deleted. - type: string - - description: Specifies the organization ID of the resource. - in: query - name: orgID - schema: - type: string - - description: Specifies the bucket ID to delete data from. - in: query - name: bucketID - schema: - description: Only points from this bucket ID are deleted. - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/DeletePredicateRequest' - description: Deletes data from an InfluxDB bucket. - required: true - responses: - '204': - description: delete has been accepted - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Invalid request. - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: no token was sent or does not have sufficient permissions. - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: the bucket or organization is not found. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: internal server error - summary: Delete data - tags: - - Delete - /api/v2/flags: - get: - operationId: GetFlags - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Flags' - description: Feature flags for the currently authenticated user - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Return the feature flags for the currently authenticated user - tags: - - Users - /api/v2/labels: - get: - operationId: GetLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: query - name: orgID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of labels - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels - tags: - - Labels - post: - operationId: PostLabels - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelCreateRequest' - description: Label to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: Added label - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a label - tags: - - Labels - /api/v2/labels/{labelID}: - delete: - operationId: DeleteLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Label not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label - tags: - - Labels - get: - operationId: GetLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the label to update. - in: path - name: labelID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: A label - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a label - tags: - - Labels - patch: - operationId: PatchLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the label to update. - in: path - name: labelID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelUpdate' - description: Label update - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: Updated label - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Label not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a label - tags: - - Labels - /api/v2/maps/mapToken: - get: - operationId: getMapboxToken - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Token' - description: A temp token for Mapbox - '401': - $ref: '#/components/responses/ServerError' - '500': - $ref: '#/components/responses/ServerError' - default: - $ref: '#/components/responses/ServerError' - /api/v2/me: - get: - operationId: GetMe - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/UserResponse' - description: The currently authenticated user. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve the currently authenticated user - tags: - - Users - /api/v2/me/password: - put: - operationId: PutMePassword - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PasswordResetBody' - description: New password - required: true - responses: - '204': - description: Password successfully updated - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unsuccessful authentication - security: - - BasicAuthentication: [] - summary: Update a password - tags: - - Users - /api/v2/notificationEndpoints: - get: - operationId: GetNotificationEndpoints - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - description: >- - Only show notification endpoints that belong to specific - organization ID. - in: query - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoints' - description: A list of notification endpoints - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all notification endpoints - tags: - - NotificationEndpoints - post: - operationId: CreateNotificationEndpoint - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PostNotificationEndpoint' - description: Notification endpoint to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoint' - description: Notification endpoint created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a notification endpoint - tags: - - NotificationEndpoints - /api/v2/notificationEndpoints/{endpointID}: - delete: - operationId: DeleteNotificationEndpointsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The endpoint was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a notification endpoint - tags: - - NotificationEndpoints - get: - operationId: GetNotificationEndpointsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoint' - description: The notification endpoint requested - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a notification endpoint - tags: - - NotificationEndpoints - patch: - operationId: PatchNotificationEndpointsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpointUpdate' - description: Check update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoint' - description: An updated notification endpoint - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The notification endpoint was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a notification endpoint - tags: - - NotificationEndpoints - put: - operationId: PutNotificationEndpointsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoint' - description: A new notification endpoint to replace the existing endpoint with - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoint' - description: An updated notification endpoint - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The notification endpoint was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a notification endpoint - tags: - - NotificationEndpoints - /api/v2/notificationEndpoints/{endpointID}/labels: - get: - operationId: GetNotificationEndpointsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a notification endpoint - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a notification endpoint - tags: - - NotificationEndpoints - post: - operationId: PostNotificationEndpointIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The label was added to the notification endpoint - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a notification endpoint - tags: - - NotificationEndpoints - /api/v2/notificationEndpoints/{endpointID}/labels/{labelID}: - delete: - operationId: DeleteNotificationEndpointsIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Endpoint or label not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a notification endpoint - tags: - - NotificationEndpoints - /api/v2/notificationRules: - get: - operationId: GetNotificationRules - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - description: >- - Only show notification rules that belong to a specific organization - ID. - in: query - name: orgID - required: true - schema: - type: string - - description: Only show notifications that belong to the specific check ID. - in: query - name: checkID - schema: - type: string - - description: >- - Only return notification rules that "would match" statuses which - contain the tag key value pairs provided. - in: query - name: tag - schema: - example: env:prod - pattern: ^[a-zA-Z0-9_]+:[a-zA-Z0-9_]+$ - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRules' - description: A list of notification rules - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all notification rules - tags: - - NotificationRules - post: - operationId: CreateNotificationRule - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PostNotificationRule' - description: Notification rule to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRule' - description: Notification rule created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a notification rule - tags: - - NotificationRules - /api/v2/notificationRules/{ruleID}: - delete: - operationId: DeleteNotificationRulesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The check was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a notification rule - tags: - - NotificationRules - get: - operationId: GetNotificationRulesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRule' - description: The notification rule requested - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a notification rule - tags: - - NotificationRules - patch: - operationId: PatchNotificationRulesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRuleUpdate' - description: Notification rule update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRule' - description: An updated notification rule - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The notification rule was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a notification rule - tags: - - NotificationRules - put: - operationId: PutNotificationRulesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRule' - description: Notification rule update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRule' - description: An updated notification rule - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The notification rule was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a notification rule - tags: - - NotificationRules - /api/v2/notificationRules/{ruleID}/labels: - get: - operationId: GetNotificationRulesIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a notification rule - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a notification rule - tags: - - NotificationRules - post: - operationId: PostNotificationRuleIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The label was added to the notification rule - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a notification rule - tags: - - NotificationRules - /api/v2/notificationRules/{ruleID}/labels/{labelID}: - delete: - operationId: DeleteNotificationRulesIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Rule or label not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete label from a notification rule - tags: - - NotificationRules - /api/v2/notificationRules/{ruleID}/query: - get: - operationId: GetNotificationRulesIDQuery - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/FluxResponse' - description: The notification rule query requested - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Invalid request - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Notification rule not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a notification rule query - tags: - - Rules - /api/v2/orgs: - get: - operationId: GetOrgs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - $ref: '#/components/parameters/Descending' - - description: Filter organizations to a specific organization name. - in: query - name: org - schema: - type: string - - description: Filter organizations to a specific organization ID. - in: query - name: orgID - schema: - type: string - - description: Filter organizations to a specific user ID. - in: query - name: userID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Organizations' - description: A list of organizations - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all organizations - tags: - - Organizations - post: - operationId: PostOrgs - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PostOrganizationRequest' - description: Organization to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Organization' - description: Organization created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create an organization - tags: - - Organizations - /api/v2/orgs/{orgID}: - delete: - operationId: DeleteOrgsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the organization to delete. - in: path - name: orgID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Organization not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete an organization - tags: - - Organizations - get: - operationId: GetOrgsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the organization to get. - in: path - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Organization' - description: Organization details - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve an organization - tags: - - Organizations - patch: - operationId: PatchOrgsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the organization to get. - in: path - name: orgID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PatchOrganizationRequest' - description: Organization update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Organization' - description: Organization updated - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update an organization - tags: - - Organizations - /api/v2/orgs/{orgID}/members: - get: - operationId: GetOrgsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMembers' - description: A list of organization members - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Organization not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all members of an organization - tags: - - Organizations - post: - operationId: PostOrgsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as member - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMember' - description: Added to organization created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to an organization - tags: - - Organizations - /api/v2/orgs/{orgID}/members/{userID}: - delete: - operationId: DeleteOrgsIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the member to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - responses: - '204': - description: Member removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from an organization - tags: - - Organizations - /api/v2/orgs/{orgID}/owners: - get: - operationId: GetOrgsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwners' - description: A list of organization owners - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Organization not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all owners of an organization - tags: - - Organizations - post: - operationId: PostOrgsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as owner - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwner' - description: Organization owner added - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add an owner to an organization - tags: - - Organizations - /api/v2/orgs/{orgID}/owners/{userID}: - delete: - operationId: DeleteOrgsIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the owner to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - responses: - '204': - description: Owner removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from an organization - tags: - - Organizations - /api/v2/orgs/{orgID}/secrets: - get: - operationId: GetOrgsIDSecrets - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/SecretKeysResponse' - description: A list of all secret keys - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all secret keys for an organization - tags: - - Secrets - patch: - operationId: PatchOrgsIDSecrets - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Secrets' - description: Secret key value pairs to update/add - required: true - responses: - '204': - description: Keys successfully patched - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update secrets in an organization - tags: - - Secrets - /api/v2/orgs/{orgID}/secrets/{secretID}: - delete: - operationId: DeleteOrgsIDSecretsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - - description: The secret ID. - in: path - name: secretID - required: true - schema: - type: string - responses: - '204': - description: Keys successfully deleted - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Delete a secret from an organization - tags: - - Secrets - /api/v2/orgs/{orgID}/secrets/delete: - post: - deprecated: true - operationId: PostOrgsIDSecrets - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/SecretKeys' - description: Secret key to delete - required: true - responses: - '204': - description: Keys successfully patched - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete secrets from an organization - tags: - - Secrets - /ping: - get: - operationId: GetPing - responses: - '204': - description: OK - headers: - X-Influxdb-Build: - description: The type of InfluxDB build. - schema: - type: string - X-Influxdb-Version: - description: The version of InfluxDB. - schema: - type: integer - servers: - - url: / - summary: Checks the status of InfluxDB instance and version of InfluxDB. - tags: - - Ping - head: - operationId: HeadPing - responses: - '204': - description: OK - headers: - X-Influxdb-Build: - description: The type of InfluxDB build. - schema: - type: string - X-Influxdb-Version: - description: The version of InfluxDB. - schema: - type: integer - servers: - - url: / - summary: Checks the status of InfluxDB instance and version of InfluxDB. - tags: - - Ping - /api/v2/query: - post: - description: > - Retrieves data from InfluxDB buckets. - - - To query data, you need the following: - - - **organization** – _See [View - organizations](https://docs.influxdata.com/influxdb/v2.0/organizations/view-orgs/#view-your-organization-id) - for instructions on viewing your organization ID._ - - - **API token** – _See [View - tokens](https://docs.influxdata.com/influxdb/v2.0/security/tokens/view-tokens/) - for instructions on viewing your API token._ - - **InfluxDB URL** – _See [InfluxDB - URLs](https://docs.influxdata.com/influxdb/v2.0/reference/urls/)_. - - - **Flux query** – _See [Flux](https://docs.influxdata.com/flux/v0.x/)._ - - - For more information and examples, see [Query with the InfluxDB - API](https://docs.influxdata.com/influxdb/v2.0/query-data/execute-queries/influx-api/). - operationId: PostQuery - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: >- - The Accept-Encoding request HTTP header advertises which content - encoding, usually a compression algorithm, the client is able to - understand. - in: header - name: Accept-Encoding - schema: - default: identity - description: >- - Specifies that the query response in the body should be encoded - with gzip or not encoded with identity. - enum: - - gzip - - identity - type: string - - in: header - name: Content-Type - schema: - enum: - - application/json - - application/vnd.flux - type: string - - description: >- - Specifies the name of the organization executing the query. Takes - either the ID or Name. If both `orgID` and `org` are specified, - `org` takes precedence. - in: query - name: org - schema: - type: string - - description: >- - Specifies the ID of the organization executing the query. If both - `orgID` and `org` are specified, `org` takes precedence. - in: query - name: orgID - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Query' - application/vnd.flux: - schema: - type: string - example: | - from(bucket: "example-bucket") - |> range(start: -5m) - |> filter(fn: (r) => r._measurement == "example-measurement") - description: Flux query or specification to execute - responses: - '200': - content: - application/vnd.influx.arrow: - schema: - format: binary - type: string - text/csv: - schema: - example: > - result,table,_start,_stop,_time,region,host,_value - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 - type: string - description: Success. Returns query results. - headers: - Content-Encoding: - description: >- - The Content-Encoding entity header is used to compress the - media-type. When present, its value indicates which encodings - were applied to the entity-body - schema: - default: identity - description: >- - Specifies that the response in the body is encoded with gzip - or not encoded with identity. - enum: - - gzip - - identity - type: string - Trace-Id: - description: >- - The Trace-Id header reports the request's trace ID, if one was - generated. - schema: - description: Specifies the request's trace ID. - type: string - '429': - description: >- - Token is temporarily over quota. The Retry-After header describes - when to try the read again. - headers: - Retry-After: - description: >- - A non-negative decimal integer indicating the seconds to delay - after the response is received. - schema: - format: int32 - type: integer - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Error processing query - summary: Query data - tags: - - Query - /api/v2/query/analyze: - post: - operationId: PostQueryAnalyze - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: header - name: Content-Type - schema: - enum: - - application/json - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Query' - description: Flux query to analyze - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/AnalyzeQueryResponse' - description: Query analyze results. Errors will be empty if the query is valid. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - headers: - X-Influx-Error: - description: Error string describing the problem - schema: - type: string - X-Influx-Reference: - description: Reference code unique to the error type - schema: - type: integer - summary: Analyze a Flux query - tags: - - Query - /api/v2/query/ast: - post: - description: Analyzes flux query and generates a query specification. - operationId: PostQueryAst - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: header - name: Content-Type - schema: - enum: - - application/json - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LanguageRequest' - description: Analyzed Flux query to generate abstract syntax tree. - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ASTResponse' - description: Abstract syntax tree of the flux query. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Any response other than 200 is an internal server error - summary: Generate an Abstract Syntax Tree (AST) from a query - tags: - - Query - /api/v2/query/suggestions: - get: - operationId: GetQuerySuggestions - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/FluxSuggestions' - description: Suggestions for next functions in call chain - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Any response other than 200 is an internal server error - summary: Retrieve query suggestions - tags: - - Query - /api/v2/query/suggestions/{name}: - get: - operationId: GetQuerySuggestionsName - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The name of the branching suggestion. - in: path - name: name - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/FluxSuggestion' - description: Suggestions for next functions in call chain - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Any response other than 200 is an internal server error - summary: Retrieve query suggestions for a branching suggestion - tags: - - Query - /api/v2/remotes: - get: - operationId: GetRemoteConnections - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: query - name: orgID - required: true - schema: - type: string - - in: query - name: name - schema: - type: string - - in: query - name: remoteURL - schema: - format: uri - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/RemoteConnections' - description: List of remote connections - '404': - $ref: '#/components/responses/ServerError' - default: - $ref: '#/components/responses/ServerError' - summary: List all remote connections - tags: - - RemoteConnections - post: - operationId: PostRemoteConnection - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: If true, validate the remote connection, but don't save it. - in: query - name: validate - schema: - default: false - type: boolean - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/RemoteConnectionCreationRequest' - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/RemoteConnection' - description: Remote connection saved - '204': - description: Remote connection validated, but not saved - '400': - $ref: '#/components/responses/ServerError' - default: - $ref: '#/components/responses/ServerError' - summary: Register a new remote connection - tags: - - RemoteConnections - /api/v2/remotes/{remoteID}: - delete: - operationId: DeleteRemoteConnectionByID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: remoteID - required: true - schema: - type: string - responses: - '204': - description: Remote connection info deleted. - '404': - $ref: '#/components/responses/ServerError' - default: - $ref: '#/components/responses/ServerError' - summary: Delete a remote connection - tags: - - RemoteConnections - get: - operationId: GetRemoteConnectionByID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: remoteID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/RemoteConnection' - description: Remote connection - '404': - $ref: '#/components/responses/ServerError' - default: - $ref: '#/components/responses/ServerError' - summary: Retrieve a remote connection - tags: - - RemoteConnections - patch: - operationId: PatchRemoteConnectionByID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: remoteID - required: true - schema: - type: string - - description: If true, validate the updated information, but don't save it. - in: query - name: validate - schema: - default: false - type: boolean - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/RemoteConnectionUpdateRequest' - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/RemoteConnection' - description: Updated information saved - '204': - description: Updated connection validated, but not saved - '400': - $ref: '#/components/responses/ServerError' - '404': - $ref: '#/components/responses/ServerError' - default: - $ref: '#/components/responses/ServerError' - summary: Update a remote connection - tags: - - RemoteConnections - /api/v2/remotes/{remoteID}/validate: - post: - operationId: PostValidateRemoteConnectionByID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: remoteID - required: true - schema: - type: string - responses: - '204': - description: Remote connection is valid - '400': - $ref: '#/components/responses/ServerError' - description: Remote connection failed validation - default: - $ref: '#/components/responses/ServerError' - summary: Validate a remote connection - tags: - - RemoteConnections - /api/v2/replications: - get: - operationId: GetReplications - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: query - name: orgID - required: true - schema: - type: string - - in: query - name: name - schema: - type: string - - in: query - name: remoteID - schema: - type: string - - in: query - name: localBucketID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Replications' - description: List of replications - '404': - $ref: '#/components/responses/ServerError' - default: - $ref: '#/components/responses/ServerError' - summary: List all replications - tags: - - Replications - post: - operationId: PostReplication - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: If true, validate the replication, but don't save it. - in: query - name: validate - schema: - default: false - type: boolean - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/ReplicationCreationRequest' - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Replication' - description: Replication saved - '204': - description: Replication validated, but not saved - '400': - $ref: '#/components/responses/ServerError' - default: - $ref: '#/components/responses/ServerError' - summary: Register a new replication - tags: - - Replications - /api/v2/replications/{replicationID}: - delete: - operationId: DeleteReplicationByID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: replicationID - required: true - schema: - type: string - responses: - '204': - description: Replication deleted. - '404': - $ref: '#/components/responses/ServerError' - default: - $ref: '#/components/responses/ServerError' - summary: Delete a replication - tags: - - Replications - get: - operationId: GetReplicationByID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: replicationID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Replication' - description: Replication - '404': - $ref: '#/components/responses/ServerError' - default: - $ref: '#/components/responses/ServerError' - summary: Retrieve a replication - tags: - - Replications - patch: - operationId: PatchReplicationByID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: replicationID - required: true - schema: - type: string - - description: If true, validate the updated information, but don't save it. - in: query - name: validate - schema: - default: false - type: boolean - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/ReplicationUpdateRequest' - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Replication' - description: Updated information saved - '204': - description: Updated replication validated, but not saved - '400': - $ref: '#/components/responses/ServerError' - '404': - $ref: '#/components/responses/ServerError' - default: - $ref: '#/components/responses/ServerError' - summary: Update a replication - tags: - - Replications - /api/v2/replications/{replicationID}/validate: - post: - operationId: PostValidateReplicationByID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: replicationID - required: true - schema: - type: string - responses: - '204': - description: Replication is valid - '400': - $ref: '#/components/responses/ServerError' - description: Replication failed validation - default: - $ref: '#/components/responses/ServerError' - summary: Validate a replication - tags: - - Replications - /api/v2/resources: - get: - operationId: GetResources - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - items: - type: string - type: array - description: All resources targets - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - summary: List all known resources - tags: - - Resources - /api/v2/restore/bucket/{bucketID}: - post: - deprecated: true - operationId: PostRestoreBucketID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. - in: path - name: bucketID - required: true - schema: - type: string - - in: header - name: Content-Type - schema: - default: application/octet-stream - enum: - - application/octet-stream - type: string - requestBody: - content: - text/plain: - schema: - format: byte - type: string - description: Database info serialized as protobuf. - required: true - responses: - '200': - content: - application/json: - schema: - format: byte - type: string - description: ID mappings for shards in bucket. - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Overwrite storage metadata for a bucket with shard info from a backup. - tags: - - Restore - /api/v2/restore/bucketMetadata: - post: - operationId: PostRestoreBucketMetadata - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/BucketMetadataManifest' - description: Metadata manifest for a bucket. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/RestoredBucketMappings' - description: ID mappings for shards in new bucket. - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Create a new bucket pre-seeded with shard info from a backup. - tags: - - Restore - /api/v2/restore/kv: - post: - operationId: PostRestoreKV - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: >- - When present, its value indicates to the database that compression - is applied to the line-protocol body. - in: header - name: Content-Encoding - schema: - default: identity - description: >- - Specifies that the line protocol in the body is encoded with gzip - or not encoded with identity. - enum: - - gzip - - identity - type: string - - in: header - name: Content-Type - schema: - default: application/octet-stream - enum: - - application/octet-stream - type: string - requestBody: - content: - text/plain: - schema: - format: binary - type: string - description: Full KV snapshot. - required: true - responses: - '200': - content: - application/json: - schema: - properties: - token: - description: >- - token is the root token for the instance after restore - (this is overwritten during the restore) - type: string - type: object - description: KV store successfully overwritten. - '204': - description: KV store successfully overwritten. - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Overwrite the embedded KV store on the server with a backed-up snapshot. - tags: - - Restore - /api/v2/restore/shards/{shardID}: - post: - operationId: PostRestoreShardId - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: >- - When present, its value indicates to the database that compression - is applied to the line-protocol body. - in: header - name: Content-Encoding - schema: - default: identity - description: >- - Specifies that the line protocol in the body is encoded with gzip - or not encoded with identity. - enum: - - gzip - - identity - type: string - - in: header - name: Content-Type - schema: - default: application/octet-stream - enum: - - application/octet-stream - type: string - - description: The shard ID. - in: path - name: shardID - required: true - schema: - type: string - requestBody: - content: - text/plain: - schema: - format: binary - type: string - description: TSM snapshot. - required: true - responses: - '204': - description: TSM snapshot successfully restored. - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Restore a TSM snapshot into a shard. - tags: - - Restore - /api/v2/restore/sql: - post: - operationId: PostRestoreSQL - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: >- - When present, its value indicates to the database that compression - is applied to the line-protocol body. - in: header - name: Content-Encoding - schema: - default: identity - description: >- - Specifies that the line protocol in the body is encoded with gzip - or not encoded with identity. - enum: - - gzip - - identity - type: string - - in: header - name: Content-Type - schema: - default: application/octet-stream - enum: - - application/octet-stream - type: string - requestBody: - content: - text/plain: - schema: - format: binary - type: string - description: Full SQL snapshot. - required: true - responses: - '204': - description: SQL store successfully overwritten. - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: >- - Overwrite the embedded SQL store on the server with a backed-up - snapshot. - tags: - - Restore - /api/v2/scrapers: - get: - operationId: GetScrapers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: Specifies the name of the scraper target. - in: query - name: name - schema: - type: string - - description: >- - List of scraper target IDs to return. If both `id` and `owner` are - specified, only `id` is used. - in: query - name: id - schema: - items: - type: string - type: array - - description: Specifies the organization ID of the scraper target. - in: query - name: orgID - schema: - type: string - - description: Specifies the organization name of the scraper target. - in: query - name: org - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ScraperTargetResponses' - description: All scraper targets - summary: List all scraper targets - tags: - - Scraper Targets - post: - operationId: PostScrapers - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/ScraperTargetRequest' - description: Scraper target to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ScraperTargetResponse' - description: Scraper target created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - summary: Create a scraper target - tags: - - Scraper Targets - /api/v2/scrapers/{scraperTargetID}: - delete: - operationId: DeleteScrapersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The identifier of the scraper target. - in: path - name: scraperTargetID - required: true - schema: - type: string - responses: - '204': - description: Scraper target deleted - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - summary: Delete a scraper target - tags: - - Scraper Targets - get: - operationId: GetScrapersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The identifier of the scraper target. - in: path - name: scraperTargetID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ScraperTargetResponse' - description: The scraper target - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - summary: Retrieve a scraper target - tags: - - Scraper Targets - patch: - operationId: PatchScrapersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The identifier of the scraper target. - in: path - name: scraperTargetID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/ScraperTargetRequest' - description: Scraper target update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ScraperTargetResponse' - description: Scraper target updated - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - summary: Update a scraper target - tags: - - Scraper Targets - /api/v2/scrapers/{scraperTargetID}/labels: - get: - operationId: GetScrapersIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of labels for a scraper target. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a scraper target - tags: - - Scraper Targets - post: - operationId: PostScrapersIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The newly added label - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a scraper target - tags: - - Scraper Targets - /api/v2/scrapers/{scraperTargetID}/labels/{labelID}: - delete: - operationId: DeleteScrapersIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - - description: The label ID. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Scraper target not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a scraper target - tags: - - Scraper Targets - /api/v2/scrapers/{scraperTargetID}/members: - get: - operationId: GetScrapersIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMembers' - description: A list of scraper target members - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all users with member privileges for a scraper target - tags: - - Scraper Targets - post: - operationId: PostScrapersIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as member - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMember' - description: Member added to scraper targets - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to a scraper target - tags: - - Scraper Targets - /api/v2/scrapers/{scraperTargetID}/members/{userID}: - delete: - operationId: DeleteScrapersIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of member to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - responses: - '204': - description: Member removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from a scraper target - tags: - - Scraper Targets - /api/v2/scrapers/{scraperTargetID}/owners: - get: - operationId: GetScrapersIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwners' - description: A list of scraper target owners - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all owners of a scraper target - tags: - - Scraper Targets - post: - operationId: PostScrapersIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as owner - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwner' - description: Scraper target owner added - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add an owner to a scraper target - tags: - - Scraper Targets - /api/v2/scrapers/{scraperTargetID}/owners/{userID}: - delete: - operationId: DeleteScrapersIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of owner to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - responses: - '204': - description: Owner removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from a scraper target - tags: - - Scraper Targets - /api/v2/setup: - get: - description: >- - Returns `true` if no default user, organization, or bucket has been - created. - operationId: GetSetup - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/IsOnboarding' - description: allowed true or false - summary: Check if database has default user, org, bucket - tags: - - Setup - post: - description: Post an onboarding request to set up initial user, org and bucket. - operationId: PostSetup - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingRequest' - description: Source to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingResponse' - description: Created default user, bucket, org - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Set up initial user, org and bucket - tags: - - Setup - /api/v2/signin: - post: - description: >- - Authenticates ***Basic Auth*** credentials for a user. If successful, - creates a new UI session for the user. - operationId: PostSignin - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '204': - description: Success. User authenticated. - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unauthorized access. - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: User account is disabled. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unsuccessful authentication. - security: - - BasicAuthentication: [] - summary: Create a user session. - tags: - - Signin - /api/v2/signout: - post: - description: Expires the current UI session for the user. - operationId: PostSignout - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '204': - description: Session successfully expired - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unauthorized access - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unsuccessful session expiry - summary: Expire the current UI session - tags: - - Signout - /api/v2/sources: - get: - operationId: GetSources - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The name of the organization. - in: query - name: org - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Sources' - description: A list of sources - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all sources - tags: - - Sources - post: - operationId: PostSources - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Source' - description: Source to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Source' - description: Created Source - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a source - tags: - - Sources - /api/v2/sources/{sourceID}: - delete: - operationId: DeleteSourcesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The source ID. - in: path - name: sourceID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: View not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a source - tags: - - Sources - get: - operationId: GetSourcesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The source ID. - in: path - name: sourceID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Source' - description: A source - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Source not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a source - tags: - - Sources - patch: - operationId: PatchSourcesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The source ID. - in: path - name: sourceID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Source' - description: Source update - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Source' - description: Created Source - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Source not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a Source - tags: - - Sources - /api/v2/sources/{sourceID}/buckets: - get: - operationId: GetSourcesIDBuckets - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The source ID. - in: path - name: sourceID - required: true - schema: - type: string - - description: The name of the organization. - in: query - name: org - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Buckets' - description: A source - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Source not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Get buckets in a source - tags: - - Sources - - Buckets - /api/v2/sources/{sourceID}/health: - get: - operationId: GetSourcesIDHealth - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The source ID. - in: path - name: sourceID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/HealthCheck' - description: The source is healthy - '503': - content: - application/json: - schema: - $ref: '#/components/schemas/HealthCheck' - description: The source is not healthy - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Get the health of a source - tags: - - Sources - /api/v2/stacks: - get: - operationId: ListStacks - parameters: - - description: The organization ID of the stacks - in: query - name: orgID - required: true - schema: - type: string - - description: A collection of names to filter the list by. - in: query - name: name - schema: - type: string - - description: A collection of stackIDs to filter the list by. - in: query - name: stackID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - properties: - stacks: - items: - $ref: '#/components/schemas/Stack' - type: array - type: object - description: Success. Returns the list of stacks. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List installed templates - tags: - - Templates - post: - operationId: CreateStack - requestBody: - content: - application/json: - schema: - properties: - description: - type: string - name: - type: string - orgID: - type: string - urls: - items: - type: string - type: array - title: PostStackRequest - type: object - description: The stack to create. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Stack' - description: Success. Returns the newly created stack. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a new stack - tags: - - Templates - /api/v2/stacks/{stack_id}: - delete: - operationId: DeleteStack - parameters: - - description: The identifier of the stack. - in: path - name: stack_id - required: true - schema: - type: string - - description: The identifier of the organization. - in: query - name: orgID - required: true - schema: - type: string - responses: - '204': - description: The stack and its associated resources were deleted. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a stack and associated resources - tags: - - Templates - get: - operationId: ReadStack - parameters: - - description: The identifier of the stack. - in: path - name: stack_id - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Stack' - description: Returns the stack. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a stack - tags: - - Templates - patch: - operationId: UpdateStack - parameters: - - description: The identifier of the stack. - in: path - name: stack_id - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - properties: - additionalResources: - items: - properties: - kind: - type: string - resourceID: - type: string - templateMetaName: - type: string - required: - - kind - - resourceID - type: object - type: array - description: - nullable: true - type: string - name: - nullable: true - type: string - templateURLs: - items: - type: string - nullable: true - type: array - title: PatchStackRequest - type: object - description: The stack to update. - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Stack' - description: Returns the updated stack. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a stack - tags: - - Templates - /api/v2/stacks/{stack_id}/uninstall: - post: - operationId: UninstallStack - parameters: - - description: The identifier of the stack. - in: path - name: stack_id - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Stack' - description: Returns the uninstalled stack. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Uninstall a stack - tags: - - Templates - /api/v2/tasks: - get: - operationId: GetTasks - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: Returns task with a specific name. - in: query - name: name - schema: - type: string - - description: Return tasks after a specified ID. - in: query - name: after - schema: - type: string - - description: Filter tasks to a specific user ID. - in: query - name: user - schema: - type: string - - description: Filter tasks to a specific organization name. - in: query - name: org - schema: - type: string - - description: Filter tasks to a specific organization ID. - in: query - name: orgID - schema: - type: string - - description: Filter tasks by a status--"inactive" or "active". - in: query - name: status - schema: - enum: - - active - - inactive - type: string - - description: The number of tasks to return - in: query - name: limit - schema: - default: 100 - maximum: 500 - minimum: 1 - type: integer - - description: Type of task, unset by default. - in: query - name: type - required: false - schema: - default: '' - enum: - - basic - - system - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Tasks' - description: A list of tasks - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all tasks - tags: - - Tasks - post: - operationId: PostTasks - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/TaskCreateRequest' - description: Task to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Task' - description: Task created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a new task - tags: - - Tasks - /api/v2/tasks/{taskID}: - delete: - description: Deletes a task and all associated records - operationId: DeleteTasksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to delete. - in: path - name: taskID - required: true - schema: - type: string - responses: - '204': - description: Task deleted - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a task - tags: - - Tasks - get: - operationId: GetTasksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Task' - description: Task details - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a task - tags: - - Tasks - patch: - description: Update a task. This will cancel all queued runs. - operationId: PatchTasksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/TaskUpdateRequest' - description: Task update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Task' - description: Task updated - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a task - tags: - - Tasks - /api/v2/tasks/{taskID}/labels: - get: - operationId: GetTasksIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a task - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a task - tags: - - Tasks - post: - operationId: PostTasksIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: A list of all labels for a task - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a task - tags: - - Tasks - /api/v2/tasks/{taskID}/labels/{labelID}: - delete: - operationId: DeleteTasksIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - - description: The label ID. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Task not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a task - tags: - - Tasks - /api/v2/tasks/{taskID}/logs: - get: - operationId: GetTasksIDLogs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Logs' - description: All logs for a task - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve all logs for a task - tags: - - Tasks - /api/v2/tasks/{taskID}/members: - get: - operationId: GetTasksIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMembers' - description: A list of users who have member privileges for a task - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all task members - tags: - - Tasks - post: - operationId: PostTasksIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as member - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMember' - description: Added to task members - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to a task - tags: - - Tasks - /api/v2/tasks/{taskID}/members/{userID}: - delete: - operationId: DeleteTasksIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the member to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - responses: - '204': - description: Member removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from a task - tags: - - Tasks - /api/v2/tasks/{taskID}/owners: - get: - operationId: GetTasksIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwners' - description: A list of users who have owner privileges for a task - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all owners of a task - tags: - - Tasks - post: - operationId: PostTasksIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as owner - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwner' - description: Added to task owners - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add an owner to a task - tags: - - Tasks - /api/v2/tasks/{taskID}/owners/{userID}: - delete: - operationId: DeleteTasksIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the owner to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - responses: - '204': - description: Owner removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from a task - tags: - - Tasks - /api/v2/tasks/{taskID}/runs: - get: - operationId: GetTasksIDRuns - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to get runs for. - in: path - name: taskID - required: true - schema: - type: string - - description: Returns runs after a specific ID. - in: query - name: after - schema: - type: string - - description: The number of runs to return - in: query - name: limit - schema: - default: 100 - maximum: 500 - minimum: 1 - type: integer - - description: Filter runs to those scheduled after this time, RFC3339 - in: query - name: afterTime - schema: - format: date-time - type: string - - description: Filter runs to those scheduled before this time, RFC3339 - in: query - name: beforeTime - schema: - format: date-time - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Runs' - description: A list of task runs - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List runs for a task - tags: - - Tasks - post: - operationId: PostTasksIDRuns - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/RunManually' - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Run' - description: Run scheduled to start - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Manually start a task run, overriding the current schedule - tags: - - Tasks - /api/v2/tasks/{taskID}/runs/{runID}: - delete: - operationId: DeleteTasksIDRunsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - - description: The run ID. - in: path - name: runID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Cancel a running task - tags: - - Tasks - get: - operationId: GetTasksIDRunsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - - description: The run ID. - in: path - name: runID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Run' - description: The run record - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a single run for a task - tags: - - Tasks - /api/v2/tasks/{taskID}/runs/{runID}/logs: - get: - operationId: GetTasksIDRunsIDLogs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: ID of task to get logs for. - in: path - name: taskID - required: true - schema: - type: string - - description: ID of run to get logs for. - in: path - name: runID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Logs' - description: All logs for a run - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve all logs for a run - tags: - - Tasks - /api/v2/tasks/{taskID}/runs/{runID}/retry: - post: - operationId: PostTasksIDRunsIDRetry - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - - description: The run ID. - in: path - name: runID - required: true - schema: - type: string - requestBody: - content: - application/json; charset=utf-8: - schema: - type: object - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Run' - description: Run that has been queued - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retry a task run - tags: - - Tasks - /api/v2/telegraf/plugins: - get: - operationId: GetTelegrafPlugins - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The type of plugin desired. - in: query - name: type - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/TelegrafPlugins' - description: A list of Telegraf plugins. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all Telegraf plugins - tags: - - Telegraf Plugins - /api/v2/telegrafs: - get: - operationId: GetTelegrafs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID the Telegraf config belongs to. - in: query - name: orgID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Telegrafs' - description: A list of Telegraf configurations - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all Telegraf configurations - tags: - - Telegrafs - post: - operationId: PostTelegrafs - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/TelegrafRequest' - description: Telegraf configuration to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Telegraf' - description: Telegraf configuration created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a Telegraf configuration - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}: - delete: - operationId: DeleteTelegrafsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf configuration ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a Telegraf configuration - tags: - - Telegrafs - get: - operationId: GetTelegrafsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf configuration ID. - in: path - name: telegrafID - required: true - schema: - type: string - - in: header - name: Accept - required: false - schema: - default: application/toml - enum: - - application/toml - - application/json - - application/octet-stream - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Telegraf' - application/octet-stream: - example: |- - [agent] - interval = "10s" - schema: - type: string - application/toml: - example: |- - [agent] - interval = "10s" - schema: - type: string - description: Telegraf configuration details - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a Telegraf configuration - tags: - - Telegrafs - put: - operationId: PutTelegrafsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/TelegrafRequest' - description: Telegraf configuration update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Telegraf' - description: An updated Telegraf configurations - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a Telegraf configuration - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/labels: - get: - operationId: GetTelegrafsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a Telegraf config - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a Telegraf config - tags: - - Telegrafs - post: - operationId: PostTelegrafsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The label added to the Telegraf config - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a Telegraf config - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/labels/{labelID}: - delete: - operationId: DeleteTelegrafsIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - - description: The label ID. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Telegraf config not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a Telegraf config - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/members: - get: - operationId: GetTelegrafsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMembers' - description: A list of Telegraf config members - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all users with member privileges for a Telegraf config - tags: - - Telegrafs - post: - operationId: PostTelegrafsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as member - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMember' - description: Member added to Telegraf config - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to a Telegraf config - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/members/{userID}: - delete: - operationId: DeleteTelegrafsIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the member to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '204': - description: Member removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from a Telegraf config - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/owners: - get: - operationId: GetTelegrafsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf configuration ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwners' - description: Returns Telegraf configuration owners as a ResourceOwners list - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all owners of a Telegraf configuration - tags: - - Telegrafs - post: - operationId: PostTelegrafsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf configuration ID. - in: path - name: telegrafID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as owner - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwner' - description: >- - Telegraf configuration owner was added. Returns a ResourceOwner that - references the User. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add an owner to a Telegraf configuration - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/owners/{userID}: - delete: - operationId: DeleteTelegrafsIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the owner to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '204': - description: Owner removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from a Telegraf config - tags: - - Telegrafs - /api/v2/templates/apply: - post: - description: Applies or performs a dry-run of template in an organization. - operationId: ApplyTemplate - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/TemplateApply' - application/x-jsonnet: - schema: - $ref: '#/components/schemas/TemplateApply' - text/yml: - schema: - $ref: '#/components/schemas/TemplateApply' - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/TemplateSummary' - description: > - Success. The package dry-run succeeded. No new resources were - created. Returns a diff and summary of the dry-run. The diff and - summary won't contain IDs for resources that didn't exist at the - time of the dry-run. - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/TemplateSummary' - description: > - Success. The package applied successfully. Returns a diff and - summary of the run. The summary contains newly created resources. - The diff compares the initial state to the state after the package - applied. This corresponds to `"dryRun": true`. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Apply or dry-run a template - tags: - - Templates - /api/v2/templates/export: - post: - operationId: ExportTemplate - requestBody: - content: - application/json: - schema: - oneOf: - - $ref: '#/components/schemas/TemplateExportByID' - - $ref: '#/components/schemas/TemplateExportByName' - description: Export resources as an InfluxDB template. - required: false - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Template' - application/x-yaml: - schema: - $ref: '#/components/schemas/Template' - description: >- - The template was created successfully. Returns the newly created - template. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Export a new template - tags: - - Templates - /api/v2/users: - get: - operationId: GetUsers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - $ref: '#/components/parameters/After' - - in: query - name: name - schema: - type: string - - in: query - name: id - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Users' - description: A list of users - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: List all users - tags: - - Users - post: - operationId: PostUsers - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/User' - description: User to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/UserResponse' - description: User created - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Create a user - tags: - - Users - /api/v2/users/{userID}: - delete: - operationId: DeleteUsersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the user to delete. - in: path - name: userID - required: true - schema: - type: string - responses: - '204': - description: User deleted - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Delete a user - tags: - - Users - get: - operationId: GetUsersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The user ID. - in: path - name: userID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/UserResponse' - description: User details - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Retrieve a user - tags: - - Users - patch: - operationId: PatchUsersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the user to update. - in: path - name: userID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/User' - description: User update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/UserResponse' - description: User updated - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Update a user - tags: - - Users - /api/v2/users/{userID}/password: - post: - operationId: PostUsersIDPassword - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The user ID. - in: path - name: userID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PasswordResetBody' - description: New password - required: true - responses: - '204': - description: Password successfully updated - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unsuccessful authentication - security: - - BasicAuthentication: [] - summary: Update a password - tags: - - Users - /api/v2/variables: - get: - operationId: GetVariables - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The name of the organization. - in: query - name: org - schema: - type: string - - description: The organization ID. - in: query - name: orgID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Variables' - description: A list of variables for an organization - '400': - $ref: '#/components/responses/ServerError' - description: Invalid request - default: - $ref: '#/components/responses/ServerError' - description: Internal server error - summary: List all variables - tags: - - Variables - post: - operationId: PostVariables - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable created - default: - $ref: '#/components/responses/ServerError' - description: Internal server error - summary: Create a variable - tags: - - Variables - /api/v2/variables/{variableID}: - delete: - operationId: DeleteVariablesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - responses: - '204': - description: Variable deleted - default: - $ref: '#/components/responses/ServerError' - description: Internal server error - summary: Delete a variable - tags: - - Variables - get: - operationId: GetVariablesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable found - '404': - $ref: '#/components/responses/ServerError' - description: Variable not found - default: - $ref: '#/components/responses/ServerError' - description: Internal server error - summary: Retrieve a variable - tags: - - Variables - patch: - operationId: PatchVariablesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable updated - default: - $ref: '#/components/responses/ServerError' - description: Internal server error - summary: Update a variable - tags: - - Variables - put: - operationId: PutVariablesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable to replace - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable updated - default: - $ref: '#/components/responses/ServerError' - description: Internal server error - summary: Replace a variable - tags: - - Variables - /api/v2/variables/{variableID}/labels: - get: - operationId: GetVariablesIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a variable - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a variable - tags: - - Variables - post: - operationId: PostVariablesIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The newly added label - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a variable - tags: - - Variables - /api/v2/variables/{variableID}/labels/{labelID}: - delete: - operationId: DeleteVariablesIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - - description: The label ID to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Variable not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a variable - tags: - - Variables - /api/v2/write: - post: - description: > - Writes data to a bucket. - - - To write data into InfluxDB, you need the following: - - - **organization** – _See [View - organizations](https://docs.influxdata.com/influxdb/v2.0/organizations/view-orgs/#view-your-organization-id) - for instructions on viewing your organization ID._ - - - **bucket** – _See [View - buckets](https://docs.influxdata.com/influxdb/v2.0/organizations/buckets/view-buckets/) - for - instructions on viewing your bucket ID._ - - **API token** – _See [View - tokens](https://docs.influxdata.com/influxdb/v2.0/security/tokens/view-tokens/) - for instructions on viewing your API token._ - - **InfluxDB URL** – _See [InfluxDB - URLs](https://docs.influxdata.com/influxdb/v2.0/reference/urls/)_. - - - data in [line - protocol](https://docs.influxdata.com/influxdb/v2.0/reference/syntax/line-protocol) - format. - - - For more information and examples, see [Write data with the InfluxDB - API](https://docs.influxdata.com/influxdb/v2.0/write-data/developer-tools/api). - operationId: PostWrite - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: >- - When present, the header value tells the database that compression - is applied to the line protocol in the request body. - in: header - name: Content-Encoding - schema: - default: identity - description: >- - The header value specifies that the line protocol in the request - body is encoded with gzip or not encoded with identity. - enum: - - gzip - - identity - type: string - - description: >- - The header value indicates the format of the data in the request - body. - in: header - name: Content-Type - schema: - default: text/plain; charset=utf-8 - description: > - `text/plain` specifies line protocol. `UTF-8` is the default - character set. - enum: - - text/plain - - text/plain; charset=utf-8 - - application/vnd.influx.arrow - type: string - - description: >- - The header value indicates the size of the entity-body, in bytes, - sent to the database. If the length is greater than the database's - `max body` configuration option, the server responds with status - code `413`. - in: header - name: Content-Length - schema: - description: The length in decimal number of octets. - type: integer - - description: The header value specifies the response format. - in: header - name: Accept - schema: - default: application/json - description: The response format for errors. - enum: - - application/json - type: string - - description: >- - The parameter value specifies the destination organization for - writes. The database writes all points in the batch to this - organization. If you provide both `orgID` and `org` parameters, - `org` takes precedence. - in: query - name: org - required: true - schema: - description: Organization name or ID. - type: string - - description: >- - The parameter value specifies the ID of the destination organization - for writes. If both `orgID` and `org` are specified, `org` takes - precedence. - in: query - name: orgID - schema: - type: string - - description: The destination bucket for writes. - in: query - name: bucket - required: true - schema: - description: All points within batch are written to this bucket. - type: string - - description: The precision for the unix timestamps within the body line-protocol. - in: query - name: precision - schema: - $ref: '#/components/schemas/WritePrecision' - requestBody: - content: - text/plain: - schema: - format: byte - type: string - description: Data in line protocol format. - required: true - responses: - '204': - description: >- - InfluxDB validated the request data format and accepted the data for - writing to the bucket. `204` doesn't indicate a successful write - operation since writes are asynchronous. See [how to check for write - errors](https://docs.influxdata.com/influxdb/v2.0/write-data/troubleshoot). - '400': - content: - application/json: - examples: - measurementSchemaFieldTypeConflict: - summary: >- - Example of a field type conflict thrown by an explicit - bucket schema - value: - code: invalid - message: >- - partial write error (2 written): unable to parse - 'air_sensor,service=S1,sensor=L1 - temperature="90.5",humidity=70.0 1632850122': schema: - field type for field "temperature" not permitted by - schema; got String but expected Float - schema: - $ref: '#/components/schemas/LineProtocolError' - description: >- - Bad request. The line protocol data in the request is malformed. The - response body contains the first malformed line in the data. - InfluxDB rejected the batch and did not write any data. - '401': - content: - application/json: - examples: - tokenNotAuthorized: - summary: >- - Token is not authorized to access the organization or - resource - value: - code: unauthorized - message: unauthorized access - schema: - $ref: '#/components/schemas/Error' - description: | - Unauthorized. The error may indicate one of the following: - * The `Authorization: Token` header is missing or malformed. - * The API token value is missing from the header. - * The token does not have sufficient permissions to write to this organization and bucket. - '404': - content: - application/json: - examples: - resource-not-found: - summary: Not found error - value: - code: not found - message: bucket "air_sensor" not found - schema: - $ref: '#/components/schemas/Error' - description: >- - Not found. A requested resource was not found. The response body - contains the requested resource type, e.g. `organization name` or - `bucket`, and name. - '413': - content: - application/json: - schema: - $ref: '#/components/schemas/LineProtocolLengthError' - description: > - All request data was rejected and not written. InfluxDB OSS only - returns this error if the [Go (golang) - `ioutil.ReadAll()`](https://pkg.go.dev/io/ioutil#ReadAll) function - raises an error. - '500': - content: - application/json: - examples: - internalError: - summary: Internal error example - value: - code: internal error - schema: - $ref: '#/components/schemas/Error' - description: Internal server error. - '503': - description: >- - The server is temporarily unavailable to accept writes. The - `Retry-After` header describes when to try the write again. - headers: - Retry-After: - description: >- - A non-negative decimal integer indicating the seconds to delay - after the response is received. - schema: - format: int32 - type: integer - default: - $ref: '#/components/responses/ServerError' - summary: Write data - tags: - - Write - /health: - get: - operationId: GetHealth - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/HealthCheck' - description: The instance is healthy - '503': - content: - application/json: - schema: - $ref: '#/components/schemas/HealthCheck' - description: The instance is unhealthy - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - servers: - - url: / - summary: Get the health of an instance - tags: - - Health - /legacy/authorizations: - get: - operationId: GetLegacyAuthorizations - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: Only show legacy authorizations that belong to a user ID. - in: query - name: userID - schema: - type: string - - description: Only show legacy authorizations that belong to a user name. - in: query - name: user - schema: - type: string - - description: Only show legacy authorizations that belong to an organization ID. - in: query - name: orgID - schema: - type: string - - description: Only show legacy authorizations that belong to a organization name. - in: query - name: org - schema: - type: string - - description: Only show legacy authorizations with a specified token (auth name). - in: query - name: token - schema: - type: string - - description: Only show legacy authorizations with a specified auth ID. - in: query - name: authID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorizations' - description: A list of legacy authorizations - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: List all legacy authorizations - tags: - - Legacy Authorizations - post: - operationId: PostLegacyAuthorizations - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LegacyAuthorizationPostRequest' - description: Legacy authorization to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: Legacy authorization created - '400': - $ref: '#/components/responses/ServerError' - description: Invalid request - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Create a legacy authorization - tags: - - Legacy Authorizations - servers: - - url: /private - /legacy/authorizations/{authID}: - delete: - operationId: DeleteLegacyAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the legacy authorization to delete. - in: path - name: authID - required: true - schema: - type: string - responses: - '204': - description: Legacy authorization deleted - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Delete a legacy authorization - tags: - - Legacy Authorizations - get: - operationId: GetLegacyAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the legacy authorization to get. - in: path - name: authID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: Legacy authorization details - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Retrieve a legacy authorization - tags: - - Legacy Authorizations - patch: - operationId: PatchLegacyAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the legacy authorization to update. - in: path - name: authID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - description: Legacy authorization to update - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: The active or inactive legacy authorization - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Update a legacy authorization to be active or inactive - tags: - - Legacy Authorizations - servers: - - url: /private - /legacy/authorizations/{authID}/password: - post: - operationId: PostLegacyAuthorizationsIDPassword - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the legacy authorization to update. - in: path - name: authID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PasswordResetBody' - description: New password - required: true - responses: - '204': - description: Legacy authorization password set - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Set a legacy authorization password - tags: - - Legacy Authorizations - servers: - - url: /private - /ready: - get: - operationId: GetReady - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Ready' - description: The instance is ready - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - servers: - - url: / - summary: Get the readiness of an instance at startup - tags: - - Ready components: parameters: After: @@ -7582,6 +50,13 @@ components: required: false schema: type: string + responses: + ServerError: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Non 2XX error response from server. schemas: ASTResponse: description: Contains the AST for the supplied Flux query @@ -10734,82 +3209,6 @@ components: value: type: string type: object - RemoteConnection: - properties: - allowInsecureTLS: - default: false - type: boolean - description: - type: string - id: - type: string - name: - type: string - orgID: - type: string - remoteOrgID: - type: string - remoteURL: - format: uri - type: string - required: - - id - - name - - orgID - - remoteURL - - remoteOrgID - - allowInsecureTLS - type: object - RemoteConnectionCreationRequest: - properties: - allowInsecureTLS: - default: false - type: boolean - description: - type: string - name: - type: string - orgID: - type: string - remoteAPIToken: - type: string - remoteOrgID: - type: string - remoteURL: - format: uri - type: string - required: - - name - - orgID - - remoteURL - - remoteAPIToken - - remoteOrgID - - allowInsecureTLS - type: object - RemoteConnectionUpdateRequest: - properties: - allowInsecureTLS: - default: false - type: boolean - description: - type: string - name: - type: string - remoteAPIToken: - type: string - remoteOrgID: - type: string - remoteURL: - format: uri - type: string - type: object - RemoteConnections: - properties: - remotes: - items: - $ref: '#/components/schemas/RemoteConnection' - type: array - type: object RenamableField: description: Describes a field that can be renamed and made visible or invisible. properties: @@ -10824,91 +3223,6 @@ components: description: Indicates whether this field should be visible on the table. type: boolean type: object - Replication: - properties: - currentQueueSizeBytes: - format: int64 - type: integer - description: - type: string - id: - type: string - latestErrorMessage: - type: string - latestResponseCode: - type: integer - localBucketID: - type: string - maxQueueSizeBytes: - format: int64 - type: integer - name: - type: string - orgID: - type: string - remoteBucketID: - type: string - remoteID: - type: string - required: - - id - - name - - remoteID - - orgID - - localBucketID - - remoteBucketID - - maxQueueSizeBytes - - currentQueueSizeBytes - type: object - ReplicationCreationRequest: - properties: - description: - type: string - localBucketID: - type: string - maxQueueSizeBytes: - default: 67108860 - format: int64 - minimum: 33554430 - type: integer - name: - type: string - orgID: - type: string - remoteBucketID: - type: string - remoteID: - type: string - required: - - name - - orgID - - remoteID - - localBucketID - - remoteBucketID - - maxQueueSizeBytes - type: object - ReplicationUpdateRequest: - properties: - description: - type: string - maxQueueSizeBytes: - format: int64 - minimum: 33554430 - type: integer - name: - type: string - remoteBucketID: - type: string - remoteID: - type: string - type: object - Replications: - properties: - replications: - items: - $ref: '#/components/schemas/Replication' - type: array - type: object Resource: properties: id: @@ -10949,6 +3263,9 @@ components: - checks - dbrp - notebooks + - annotations + - remotes + - replications type: string required: - type @@ -11656,6 +3973,7 @@ components: items: enum: - flux + - influxql type: string readOnly: true type: array @@ -12481,17 +4799,121 @@ components: type: string name: type: string - retentionRules: - $ref: '#/components/schemas/RetentionRules' + retentionRules: + $ref: '#/components/schemas/RetentionRules' + type: object + old: + properties: + description: + type: string + name: + type: string + retentionRules: + $ref: '#/components/schemas/RetentionRules' + type: object + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + checks: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + $ref: '#/components/schemas/CheckDiscriminator' + old: + $ref: '#/components/schemas/CheckDiscriminator' + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + dashboards: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + properties: + charts: + items: + $ref: '#/components/schemas/TemplateChart' + type: array + description: + type: string + name: + type: string + type: object + old: + properties: + charts: + items: + $ref: '#/components/schemas/TemplateChart' + type: array + description: + type: string + name: + type: string + type: object + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + labelMappings: + items: + properties: + labelID: + type: string + labelName: + type: string + labelTemplateMetaName: + type: string + resourceID: + type: string + resourceName: + type: string + resourceTemplateMetaName: + type: string + resourceType: + type: string + status: + type: string + type: object + type: array + labels: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + properties: + color: + type: string + description: + type: string + name: + type: string type: object old: properties: + color: + type: string description: type: string name: type: string - retentionRules: - $ref: '#/components/schemas/RetentionRules' type: object stateStatus: type: string @@ -12499,7 +4921,7 @@ components: type: string type: object type: array - checks: + notificationEndpoints: items: properties: id: @@ -12507,16 +4929,16 @@ components: kind: $ref: '#/components/schemas/TemplateKind' new: - $ref: '#/components/schemas/CheckDiscriminator' + $ref: '#/components/schemas/NotificationEndpointDiscriminator' old: - $ref: '#/components/schemas/CheckDiscriminator' + $ref: '#/components/schemas/NotificationEndpointDiscriminator' stateStatus: type: string templateMetaName: type: string type: object type: array - dashboards: + notificationRules: items: properties: id: @@ -12525,27 +4947,277 @@ components: $ref: '#/components/schemas/TemplateKind' new: properties: - charts: - items: - $ref: '#/components/schemas/TemplateChart' - type: array description: type: string + endpointID: + type: string + endpointName: + type: string + endpointType: + type: string + every: + type: string + messageTemplate: + type: string name: type: string + offset: + type: string + status: + type: string + statusRules: + items: + properties: + currentLevel: + type: string + previousLevel: + type: string + type: object + type: array + tagRules: + items: + properties: + key: + type: string + operator: + type: string + value: + type: string + type: object + type: array type: object old: properties: - charts: + description: + type: string + endpointID: + type: string + endpointName: + type: string + endpointType: + type: string + every: + type: string + messageTemplate: + type: string + name: + type: string + offset: + type: string + status: + type: string + statusRules: items: - $ref: '#/components/schemas/TemplateChart' + properties: + currentLevel: + type: string + previousLevel: + type: string + type: object + type: array + tagRules: + items: + properties: + key: + type: string + operator: + type: string + value: + type: string + type: object type: array + type: object + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + tasks: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + properties: + cron: + type: string + description: + type: string + every: + type: string + name: + type: string + offset: + type: string + query: + type: string + status: + type: string + type: object + old: + properties: + cron: + type: string + description: + type: string + every: + type: string + name: + type: string + offset: + type: string + query: + type: string + status: + type: string + type: object + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + telegrafConfigs: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + $ref: '#/components/schemas/TelegrafRequest' + old: + $ref: '#/components/schemas/TelegrafRequest' + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + variables: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + properties: + args: + $ref: '#/components/schemas/VariableProperties' + description: + type: string + name: + type: string + type: object + old: + properties: + args: + $ref: '#/components/schemas/VariableProperties' description: type: string name: type: string type: object - stateStatus: + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + type: object + errors: + items: + properties: + fields: + items: + type: string + type: array + indexes: + items: + type: integer + type: array + kind: + $ref: '#/components/schemas/TemplateKind' + reason: + type: string + type: object + type: array + sources: + items: + type: string + type: array + stackID: + type: string + summary: + properties: + buckets: + items: + properties: + description: + type: string + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + name: + type: string + orgID: + type: string + retentionPeriod: + type: integer + templateMetaName: + type: string + type: object + type: array + checks: + items: + allOf: + - $ref: '#/components/schemas/CheckDiscriminator' + - properties: + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + templateMetaName: + type: string + type: object + type: array + dashboards: + items: + properties: + charts: + items: + $ref: '#/components/schemas/TemplateChart' + type: array + description: + type: string + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + name: + type: string + orgID: type: string templateMetaName: type: string @@ -12574,143 +5246,82 @@ components: type: array labels: items: - properties: - id: - type: string - kind: - $ref: '#/components/schemas/TemplateKind' - new: - properties: - color: - type: string - description: - type: string - name: - type: string - type: object - old: - properties: - color: - type: string - description: - type: string - name: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + missingEnvRefs: + items: + type: string + type: array + missingSecrets: + items: + type: string + type: array + notificationEndpoints: + items: + allOf: + - $ref: '#/components/schemas/NotificationEndpointDiscriminator' + - properties: + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + templateMetaName: type: string type: object - stateStatus: - type: string - templateMetaName: - type: string - type: object type: array - notificationEndpoints: + notificationRules: items: properties: - id: + description: type: string - kind: - $ref: '#/components/schemas/TemplateKind' - new: - $ref: '#/components/schemas/NotificationEndpointDiscriminator' - old: - $ref: '#/components/schemas/NotificationEndpointDiscriminator' - stateStatus: + endpointID: type: string - templateMetaName: + endpointTemplateMetaName: type: string - type: object - type: array - notificationRules: - items: - properties: - id: + endpointType: + type: string + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + every: type: string kind: $ref: '#/components/schemas/TemplateKind' - new: - properties: - description: - type: string - endpointID: - type: string - endpointName: - type: string - endpointType: - type: string - every: - type: string - messageTemplate: - type: string - name: - type: string - offset: - type: string - status: - type: string - statusRules: - items: - properties: - currentLevel: - type: string - previousLevel: - type: string - type: object - type: array - tagRules: - items: - properties: - key: - type: string - operator: - type: string - value: - type: string - type: object - type: array - type: object - old: - properties: - description: - type: string - endpointID: - type: string - endpointName: - type: string - endpointType: - type: string - every: - type: string - messageTemplate: - type: string - name: - type: string - offset: - type: string - status: - type: string - statusRules: - items: - properties: - currentLevel: - type: string - previousLevel: - type: string - type: object - type: array - tagRules: - items: - properties: - key: - type: string - operator: - type: string - value: - type: string - type: object - type: array - type: object - stateStatus: + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + messageTemplate: + type: string + name: type: string + offset: + type: string + status: + type: string + statusRules: + items: + properties: + currentLevel: + type: string + previousLevel: + type: string + type: object + type: array + tagRules: + items: + properties: + key: + type: string + operator: + type: string + value: + type: string + type: object + type: array templateMetaName: type: string type: object @@ -12718,869 +5329,7792 @@ components: tasks: items: properties: - id: + cron: type: string - kind: - $ref: '#/components/schemas/TemplateKind' - new: - properties: - cron: - type: string - description: - type: string - every: - type: string - name: - type: string - offset: - type: string - query: - type: string - status: - type: string - type: object - old: - properties: - cron: - type: string - description: - type: string - every: - type: string - name: - type: string - offset: - type: string - query: - type: string - status: - type: string - type: object - stateStatus: + description: + type: string + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + every: + type: string + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + name: + type: string + offset: + type: string + query: + type: string + status: type: string templateMetaName: type: string type: object type: array telegrafConfigs: + items: + allOf: + - $ref: '#/components/schemas/TelegrafRequest' + - properties: + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + templateMetaName: + type: string + type: object + type: array + variables: items: properties: + arguments: + $ref: '#/components/schemas/VariableProperties' + description: + type: string + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' id: type: string kind: $ref: '#/components/schemas/TemplateKind' - new: - $ref: '#/components/schemas/TelegrafRequest' - old: - $ref: '#/components/schemas/TelegrafRequest' - stateStatus: + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + name: + type: string + orgID: type: string templateMetaName: type: string type: object type: array - variables: + type: object + type: object + TemplateSummaryLabel: + properties: + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + name: + type: string + orgID: + type: string + properties: + properties: + color: + type: string + description: + type: string + type: object + templateMetaName: + type: string + type: object + TestStatement: + description: Declares a Flux test case + properties: + assignment: + $ref: '#/components/schemas/VariableAssignment' + type: + $ref: '#/components/schemas/NodeType' + type: object + Threshold: + discriminator: + mapping: + greater: '#/components/schemas/GreaterThreshold' + lesser: '#/components/schemas/LesserThreshold' + range: '#/components/schemas/RangeThreshold' + propertyName: type + oneOf: + - $ref: '#/components/schemas/GreaterThreshold' + - $ref: '#/components/schemas/LesserThreshold' + - $ref: '#/components/schemas/RangeThreshold' + ThresholdBase: + properties: + allValues: + description: If true, only alert if all values meet threshold. + type: boolean + level: + $ref: '#/components/schemas/CheckStatusLevel' + ThresholdCheck: + allOf: + - $ref: '#/components/schemas/CheckBase' + - properties: + every: + description: Check repetition interval. + type: string + offset: + description: Duration to delay after the schedule, before executing check. + type: string + statusMessageTemplate: + description: The template used to generate and write a status message. + type: string + tags: + description: List of tags to write to each status. items: properties: - id: + key: type: string - kind: - $ref: '#/components/schemas/TemplateKind' - new: - properties: - args: - $ref: '#/components/schemas/VariableProperties' - description: - type: string - name: - type: string - type: object - old: - properties: - args: - $ref: '#/components/schemas/VariableProperties' - description: - type: string - name: - type: string - type: object - stateStatus: + value: type: string - templateMetaName: + type: object + type: array + thresholds: + items: + $ref: '#/components/schemas/Threshold' + type: array + type: + enum: + - threshold + type: string + required: + - type + type: object + Token: + properties: + token: + type: string + type: object + UnaryExpression: + description: Uses operators to act on a single operand in an expression + properties: + argument: + $ref: '#/components/schemas/Expression' + operator: + type: string + type: + $ref: '#/components/schemas/NodeType' + type: object + UnsignedIntegerLiteral: + description: Represents integer numbers + properties: + type: + $ref: '#/components/schemas/NodeType' + value: + type: string + type: object + User: + properties: + id: + readOnly: true + type: string + name: + type: string + oauthID: + type: string + status: + default: active + description: If inactive the user is inactive. + enum: + - active + - inactive + type: string + required: + - name + UserResponse: + properties: + id: + readOnly: true + type: string + links: + example: + self: /api/v2/users/1 + properties: + self: + format: uri + type: string + readOnly: true + type: object + name: + type: string + oauthID: + type: string + status: + default: active + description: If inactive the user is inactive. + enum: + - active + - inactive + type: string + required: + - name + Users: + properties: + links: + properties: + self: + format: uri + type: string + type: object + users: + items: + $ref: '#/components/schemas/UserResponse' + type: array + type: object + Variable: + properties: + arguments: + $ref: '#/components/schemas/VariableProperties' + createdAt: + format: date-time + type: string + description: + type: string + id: + readOnly: true + type: string + labels: + $ref: '#/components/schemas/Labels' + links: + properties: + labels: + format: uri + type: string + org: + format: uri + type: string + self: + format: uri + type: string + readOnly: true + type: object + name: + type: string + orgID: + type: string + selected: + items: + type: string + type: array + updatedAt: + format: date-time + type: string + required: + - name + - orgID + - arguments + type: object + VariableAssignment: + description: Represents the declaration of a variable + properties: + id: + $ref: '#/components/schemas/Identifier' + init: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + type: object + VariableProperties: + oneOf: + - $ref: '#/components/schemas/QueryVariableProperties' + - $ref: '#/components/schemas/ConstantVariableProperties' + - $ref: '#/components/schemas/MapVariableProperties' + type: object + Variables: + example: + variables: + - arguments: + type: constant + values: + - howdy + - hello + - hi + - yo + - oy + id: '1221432' + name: ':ok:' + selected: + - hello + - arguments: + type: map + values: + a: fdjaklfdjkldsfjlkjdsa + b: dfaksjfkljekfajekdljfas + c: fdjksajfdkfeawfeea + id: '1221432' + name: ':ok:' + selected: + - c + - arguments: + language: flux + query: 'from(bucket: "foo") |> showMeasurements()' + type: query + id: '1221432' + name: ':ok:' + selected: + - host + properties: + variables: + items: + $ref: '#/components/schemas/Variable' + type: array + type: object + View: + properties: + id: + readOnly: true + type: string + links: + properties: + self: + type: string + readOnly: true + type: object + name: + type: string + properties: + $ref: '#/components/schemas/ViewProperties' + required: + - name + - properties + ViewProperties: + oneOf: + - $ref: '#/components/schemas/LinePlusSingleStatProperties' + - $ref: '#/components/schemas/XYViewProperties' + - $ref: '#/components/schemas/SingleStatViewProperties' + - $ref: '#/components/schemas/HistogramViewProperties' + - $ref: '#/components/schemas/GaugeViewProperties' + - $ref: '#/components/schemas/TableViewProperties' + - $ref: '#/components/schemas/SimpleTableViewProperties' + - $ref: '#/components/schemas/MarkdownViewProperties' + - $ref: '#/components/schemas/CheckViewProperties' + - $ref: '#/components/schemas/ScatterViewProperties' + - $ref: '#/components/schemas/HeatmapViewProperties' + - $ref: '#/components/schemas/MosaicViewProperties' + - $ref: '#/components/schemas/BandViewProperties' + - $ref: '#/components/schemas/GeoViewProperties' + Views: + properties: + links: + properties: + self: + type: string + type: object + views: + items: + $ref: '#/components/schemas/View' + type: array + type: object + WritePrecision: + enum: + - ms + - s + - us + - ns + type: string + XYGeom: + enum: + - line + - step + - stacked + - bar + - monotoneX + type: string + XYViewProperties: + properties: + axes: + $ref: '#/components/schemas/Axes' + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + generateXAxisTicks: + items: + type: string + type: array + generateYAxisTicks: + items: + type: string + type: array + geom: + $ref: '#/components/schemas/XYGeom' + hoverDimension: + enum: + - auto + - x + - 'y' + - xy + type: string + legendColorizeRows: + type: boolean + legendHide: + type: boolean + legendOpacity: + format: float + type: number + legendOrientationThreshold: + type: integer + note: + type: string + position: + enum: + - overlaid + - stacked + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shadeBelow: + type: boolean + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + staticLegend: + $ref: '#/components/schemas/StaticLegend' + timeFormat: + type: string + type: + enum: + - xy + type: string + xColumn: + type: string + xTickStart: + format: float + type: number + xTickStep: + format: float + type: number + xTotalTicks: + type: integer + yColumn: + type: string + yTickStart: + format: float + type: number + yTickStep: + format: float + type: number + yTotalTicks: + type: integer + required: + - type + - geom + - queries + - shape + - axes + - colors + - note + - showNoteWhenEmpty + - position + type: object + securitySchemes: + BasicAuthentication: + description: > + ### Basic authentication scheme + + + Use HTTP Basic Auth with clients that support the InfluxDB 1.x + convention of username and password (that don't support the + `Authorization: Token` scheme). + + + Username and password schemes require the following credentials: + - **username**: 1.x username (this is separate from the UI login username) + - **password**: 1.x password or InfluxDB API token + + #### API token example + + + `curl --get "http://localhost:8086/query" + --user "1.x_USERNAME":"INFLUX_API_TOKEN"` + + #### 1.x password example + + + `curl --get "http://localhost:8086/query" + --user "1.x_USERNAME":"1.x_PASSWORD"` + + Replace the following: + + - *`1.x_USERNAME`*: your InfluxDB v1.x username + + - *`1.x_PASSWORD`*: your InfluxDB v1.x password + + - *`INFLUX_API_TOKEN`*: your [InfluxDB API + token](https://docs.influxdata.com/influxdb/v2.0/reference/glossary/#token) + + + For more information and examples, see how to [authenticate with a + username and password + scheme](https://docs.influxdata.com/influxdb/v2.0/reference/api/influxdb-1x/) + scheme: basic + type: http + QuerystringAuthentication: + description: > + ### Querystring authentication scheme + + + Use InfluxDB 1.x API parameters to provide credentials through the query + string. + + + Username and password schemes require the following credentials: + - **username**: 1.x username (this is separate from the UI login username) + - **password**: 1.x password or InfluxDB API token + + #### API token example + + + `curl --get "http://localhost:8086/query" + --data-urlencode "u=1.x_USERNAME" + --data-urlencode "p=INFLUX_API_TOKEN"` + + #### 1.x password example + + + `curl --get "http://localhost:8086/query" + --data-urlencode "u=1.x_USERNAME" + --data-urlencode "p=1.x_PASSWORD"` + + Replace the following: + + - *`1.x_USERNAME`*: your InfluxDB v1.x username + + - *`1.x_PASSWORD`*: your InfluxDB v1.x password + + - *`INFLUX_API_TOKEN`*: your [InfluxDB API + token](https://docs.influxdata.com/influxdb/v2.0/reference/glossary/#token) + + + For more information and examples, see how to [authenticate with a + username and + password](https://docs.influxdata.com/influxdb/v2.0/reference/api/influxdb-1x/) + in: query + name: u=&p= + type: apiKey + TokenAuthentication: + bearerFormat: InfluxDB Token String + description: > + ### Token authentication scheme + + + InfluxDB API tokens enable authentication and authorization of API + clients. + + A token belongs to an organization and identifies InfluxDB permissions + within the organization. + + + Include your API token in an `Authorization: Token` HTTP header with + each request. + + + #### Example + + `curl http://localhost:8086/ping + --header "Authorization: Token INFLUX_API_TOKEN"` + + Replace *`INFLUX_API_TOKEN`* with your [InfluxDB API + token](https://docs.influxdata.com/influxdb/v2.0/reference/glossary/#token). + + For more information and examples, see the following: + - [`/authorizations`](#tag/Authorizations) endpoint. + - [Use tokens in API requests](https://docs.influxdata.com/influxdb/v2.0/api-guide/api_intro/#authentication). + - [Manage API tokens](https://docs.influxdata.com/influxdb/v2.0/security/tokens). + - [Assign a token to a specific user](https://docs.influxdata.com/influxdb/v2.0/security/tokens/create-token). + scheme: token + type: http +info: + title: Influx OSS API Service + description: > + The InfluxDB v2 API provides a programmatic interface for all interactions + with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint. +openapi: 3.0.0 +paths: + /api/v2/: + get: + operationId: GetRoutes + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Routes' + description: All routes + summary: List all top level routes + tags: + - Routes + /api/v2/authorizations: + get: + operationId: GetAuthorizations + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Only show authorizations that belong to a user ID. + in: query + name: userID + schema: + type: string + - description: Only show authorizations that belong to a user name. + in: query + name: user + schema: + type: string + - description: Only show authorizations that belong to an organization ID. + in: query + name: orgID + schema: + type: string + - description: Only show authorizations that belong to a organization name. + in: query + name: org + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorizations' + description: A list of authorizations + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: List all authorizations + tags: + - Authorizations + post: + operationId: PostAuthorizations + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationPostRequest' + description: Authorization to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + description: Authorization created + '400': + $ref: '#/components/responses/ServerError' + description: Invalid request + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Create an authorization + tags: + - Authorizations + /api/v2/authorizations/{authID}: + delete: + operationId: DeleteAuthorizationsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the authorization to delete. + in: path + name: authID + required: true + schema: + type: string + responses: + '204': + description: Authorization deleted + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Delete an authorization + tags: + - Authorizations + get: + operationId: GetAuthorizationsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the authorization to get. + in: path + name: authID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + description: Authorization details + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Retrieve an authorization + tags: + - Authorizations + patch: + operationId: PatchAuthorizationsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the authorization to update. + in: path + name: authID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationUpdateRequest' + description: Authorization to update + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + description: The active or inactive authorization + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Update an authorization to be active or inactive + tags: + - Authorizations + /api/v2/backup/kv: + get: + deprecated: true + operationId: GetBackupKV + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/octet-stream: + schema: + format: binary + type: string + description: Snapshot of KV metadata + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: >- + Download snapshot of metadata stored in the server's embedded KV store. + Should not be used in versions greater than 2.1.x, as it doesn't include + metadata stored in embedded SQL. + tags: + - Backup + /api/v2/backup/metadata: + get: + operationId: GetBackupMetadata + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: >- + The Accept-Encoding request HTTP header advertises which content + encoding, usually a compression algorithm, the client is able to + understand. + in: header + name: Accept-Encoding + schema: + default: identity + description: >- + Specifies that the query response in the body should be encoded + with gzip or not encoded with identity. + enum: + - gzip + - identity + type: string + responses: + '200': + content: + multipart/mixed: + schema: + $ref: '#/components/schemas/MetadataBackup' + description: Snapshot of metadata + headers: + Content-Encoding: + description: >- + The Content-Encoding entity header is used to compress the + media-type. When present, its value indicates which encodings + were applied to the entity-body + schema: + default: identity + description: >- + Specifies that the response in the body is encoded with gzip + or not encoded with identity. + enum: + - gzip + - identity + type: string + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Download snapshot of all metadata in the server + tags: + - Backup + /api/v2/backup/shards/{shardID}: + get: + operationId: GetBackupShardId + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: >- + The Accept-Encoding request HTTP header advertises which content + encoding, usually a compression algorithm, the client is able to + understand. + in: header + name: Accept-Encoding + schema: + default: identity + description: >- + Specifies that the query response in the body should be encoded + with gzip or not encoded with identity. + enum: + - gzip + - identity + type: string + - description: The shard ID. + in: path + name: shardID + required: true + schema: + format: int64 + type: integer + - description: Earliest time to include in the snapshot. RFC3339 format. + in: query + name: since + schema: + format: date-time + type: string + responses: + '200': + content: + application/octet-stream: + schema: + format: binary + type: string + description: TSM snapshot. + headers: + Content-Encoding: + description: >- + The Content-Encoding entity header is used to compress the + media-type. When present, its value indicates which encodings + were applied to the entity-body + schema: + default: identity + description: >- + Specifies that the response in the body is encoded with gzip + or not encoded with identity. + enum: + - gzip + - identity + type: string + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Shard not found. + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Download snapshot of all TSM data in a shard + tags: + - Backup + /api/v2/buckets: + get: + operationId: GetBuckets + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/After' + - description: The name of the organization. + in: query + name: org + schema: + type: string + - description: The organization ID. + in: query + name: orgID + schema: + type: string + - description: Only returns buckets with a specific name. + in: query + name: name + schema: + type: string + - description: Only returns buckets with a specific ID. + in: query + name: id + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Buckets' + description: A list of buckets + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all buckets + tags: + - Buckets + post: + operationId: PostBuckets + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PostBucketRequest' + description: Bucket to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Bucket' + description: Bucket created + '422': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Request body failed validation + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a bucket + tags: + - Buckets + /api/v2/buckets/{bucketID}: + delete: + operationId: DeleteBucketsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the bucket to delete. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Bucket not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a bucket + tags: + - Buckets + get: + operationId: GetBucketsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Bucket' + description: Bucket details + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a bucket + tags: + - Buckets + patch: + operationId: PatchBucketsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PatchBucketRequest' + description: Bucket update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Bucket' + description: An updated bucket + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a bucket + tags: + - Buckets + /api/v2/buckets/{bucketID}/labels: + get: + operationId: GetBucketsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a bucket + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a bucket + tags: + - Buckets + post: + operationId: PostBucketsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The newly added label + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a bucket + tags: + - Buckets + /api/v2/buckets/{bucketID}/labels/{labelID}: + delete: + operationId: DeleteBucketsIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + - description: The ID of the label to delete. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Bucket not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label from a bucket + tags: + - Buckets + /api/v2/buckets/{bucketID}/members: + get: + operationId: GetBucketsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMembers' + description: A list of bucket members + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all users with member privileges for a bucket + tags: + - Buckets + post: + operationId: PostBucketsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as member + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMember' + description: Member added to bucket + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a member to a bucket + tags: + - Buckets + /api/v2/buckets/{bucketID}/members/{userID}: + delete: + operationId: DeleteBucketsIDMembersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the member to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '204': + description: Member removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove a member from a bucket + tags: + - Buckets + /api/v2/buckets/{bucketID}/owners: + get: + operationId: GetBucketsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwners' + description: A list of bucket owners + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all owners of a bucket + tags: + - Buckets + post: + operationId: PostBucketsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as owner + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwner' + description: Bucket owner added + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add an owner to a bucket + tags: + - Buckets + /api/v2/buckets/{bucketID}/owners/{userID}: + delete: + operationId: DeleteBucketsIDOwnersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the owner to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '204': + description: Owner removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove an owner from a bucket + tags: + - Buckets + /api/v2/checks: + get: + operationId: GetChecks + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - description: Only show checks that belong to a specific organization ID. + in: query + name: orgID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Checks' + description: A list of checks + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all checks + tags: + - Checks + post: + operationId: CreateCheck + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PostCheck' + description: Check to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Check' + description: Check created + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add new check + tags: + - Checks + /api/v2/checks/{checkID}: + delete: + operationId: DeleteChecksID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The check ID. + in: path + name: checkID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The check was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a check + tags: + - Checks + get: + operationId: GetChecksID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The check ID. + in: path + name: checkID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Check' + description: The check requested + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a check + tags: + - Checks + patch: + operationId: PatchChecksID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The check ID. + in: path + name: checkID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CheckPatch' + description: Check update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Check' + description: An updated check + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The check was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a check + tags: + - Checks + put: + operationId: PutChecksID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The check ID. + in: path + name: checkID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Check' + description: Check update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Check' + description: An updated check + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The check was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a check + tags: + - Checks + /api/v2/checks/{checkID}/labels: + get: + operationId: GetChecksIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The check ID. + in: path + name: checkID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a check + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a check + tags: + - Checks + post: + operationId: PostChecksIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The check ID. + in: path + name: checkID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The label was added to the check + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a check + tags: + - Checks + /api/v2/checks/{checkID}/labels/{labelID}: + delete: + operationId: DeleteChecksIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The check ID. + in: path + name: checkID + required: true + schema: + type: string + - description: The ID of the label to delete. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Check or label not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete label from a check + tags: + - Checks + /api/v2/checks/{checkID}/query: + get: + operationId: GetChecksIDQuery + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The check ID. + in: path + name: checkID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/FluxResponse' + description: The check query requested + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Invalid request + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Check not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a check query + tags: + - Checks + /api/v2/dashboards: + get: + operationId: GetDashboards + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/Descending' + - description: >- + A user identifier. Returns only dashboards where this user has the + `owner` role. + in: query + name: owner + schema: + type: string + - description: The column to sort by. + in: query + name: sortBy + schema: + enum: + - ID + - CreatedAt + - UpdatedAt + type: string + - description: >- + A list of dashboard identifiers. Returns only the listed dashboards. + If both `id` and `owner` are specified, only `id` is used. + in: query + name: id + schema: + items: + type: string + type: array + - description: The identifier of the organization. + in: query + name: orgID + schema: + type: string + - description: The name of the organization. + in: query + name: org + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Dashboards' + description: All dashboards + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all dashboards + tags: + - Dashboards + post: + operationId: PostDashboards + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateDashboardRequest' + description: Dashboard to create + required: true + responses: + '201': + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/Dashboard' + - $ref: '#/components/schemas/DashboardWithViewProperties' + description: Added dashboard + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a dashboard + tags: + - Dashboards + /api/v2/dashboards/{dashboardID}: + delete: + operationId: DeleteDashboardsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the dashboard to update. + in: path + name: dashboardID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a dashboard + tags: + - Dashboards + get: + operationId: GetDashboardsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the dashboard to update. + in: path + name: dashboardID + required: true + schema: + type: string + - description: >- + Includes the cell view properties in the response if set to + `properties` + in: query + name: include + required: false + schema: + enum: + - properties + type: string + responses: + '200': + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/Dashboard' + - $ref: '#/components/schemas/DashboardWithViewProperties' + description: Retrieve a single dashboard + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a Dashboard + tags: + - Dashboards + patch: + operationId: PatchDashboardsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the dashboard to update. + in: path + name: dashboardID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + properties: + cells: + $ref: '#/components/schemas/CellWithViewProperties' + description: >- + optional, when provided will replace all existing cells with + the cells provided + description: + description: optional, when provided will replace the description + type: string + name: + description: optional, when provided will replace the name + type: string + title: PatchDashboardRequest + type: object + description: Patching of a dashboard + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Dashboard' + description: Updated dashboard + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a dashboard + tags: + - Dashboards + /api/v2/dashboards/{dashboardID}/cells: + post: + operationId: PostDashboardsIDCells + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the dashboard to update. + in: path + name: dashboardID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateCell' + description: Cell that will be added + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Cell' + description: Cell successfully added + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a dashboard cell + tags: + - Cells + - Dashboards + put: + description: >- + Replaces all cells in a dashboard. This is used primarily to update the + positional information of all cells. + operationId: PutDashboardsIDCells + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the dashboard to update. + in: path + name: dashboardID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Cells' + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Dashboard' + description: Replaced dashboard cells + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Replace cells in a dashboard + tags: + - Cells + - Dashboards + /api/v2/dashboards/{dashboardID}/cells/{cellID}: + delete: + operationId: DeleteDashboardsIDCellsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the dashboard to delete. + in: path + name: dashboardID + required: true + schema: + type: string + - description: The ID of the cell to delete. + in: path + name: cellID + required: true + schema: + type: string + responses: + '204': + description: Cell successfully deleted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Cell or dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a dashboard cell + tags: + - Cells + - Dashboards + patch: + description: >- + Updates the non positional information related to a cell. Updates to a + single cell's positional data could cause grid conflicts. + operationId: PatchDashboardsIDCellsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the dashboard to update. + in: path + name: dashboardID + required: true + schema: + type: string + - description: The ID of the cell to update. + in: path + name: cellID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CellUpdate' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Cell' + description: Updated dashboard cell + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Cell or dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update the non-positional information related to a cell + tags: + - Cells + - Dashboards + /api/v2/dashboards/{dashboardID}/cells/{cellID}/view: + get: + operationId: GetDashboardsIDCellsIDView + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + - description: The cell ID. + in: path + name: cellID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/View' + description: A dashboard cells view + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Cell or dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve the view for a cell + tags: + - Cells + - Dashboards + - Views + patch: + operationId: PatchDashboardsIDCellsIDView + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the dashboard to update. + in: path + name: dashboardID + required: true + schema: + type: string + - description: The ID of the cell to update. + in: path + name: cellID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/View' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/View' + description: Updated cell view + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Cell or dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update the view for a cell + tags: + - Cells + - Dashboards + - Views + /api/v2/dashboards/{dashboardID}/labels: + get: + operationId: GetDashboardsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a dashboard + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a dashboard + tags: + - Dashboards + post: + operationId: PostDashboardsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The label added to the dashboard + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a dashboard + tags: + - Dashboards + /api/v2/dashboards/{dashboardID}/labels/{labelID}: + delete: + operationId: DeleteDashboardsIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + - description: The ID of the label to delete. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label from a dashboard + tags: + - Dashboards + /api/v2/dashboards/{dashboardID}/members: + get: + operationId: GetDashboardsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMembers' + description: A list of users who have member privileges for a dashboard + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all dashboard members + tags: + - Dashboards + post: + operationId: PostDashboardsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as member + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMember' + description: Added to dashboard members + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a member to a dashboard + tags: + - Dashboards + /api/v2/dashboards/{dashboardID}/members/{userID}: + delete: + operationId: DeleteDashboardsIDMembersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the member to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + responses: + '204': + description: Member removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove a member from a dashboard + tags: + - Dashboards + /api/v2/dashboards/{dashboardID}/owners: + get: + operationId: GetDashboardsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwners' + description: A list of users who have owner privileges for a dashboard + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all dashboard owners + tags: + - Dashboards + post: + operationId: PostDashboardsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as owner + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwner' + description: Added to dashboard owners + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add an owner to a dashboard + tags: + - Dashboards + /api/v2/dashboards/{dashboardID}/owners/{userID}: + delete: + operationId: DeleteDashboardsIDOwnersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the owner to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + responses: + '204': + description: Owner removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove an owner from a dashboard + tags: + - Dashboards + /api/v2/dbrps: + get: + operationId: GetDBRPs + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Specifies the organization ID to filter on + in: query + name: orgID + schema: + type: string + - description: Specifies the organization name to filter on + in: query + name: org + schema: + type: string + - description: Specifies the mapping ID to filter on + in: query + name: id + schema: + type: string + - description: Specifies the bucket ID to filter on + in: query + name: bucketID + schema: + type: string + - description: Specifies filtering on default + in: query + name: default + schema: + type: boolean + - description: Specifies the database to filter on + in: query + name: db + schema: + type: string + - description: Specifies the retention policy to filter on + in: query + name: rp + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/DBRPs' + description: Success. Returns a list of database retention policy mappings. + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Bad request. The request has one or more invalid parameters. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List database retention policy mappings + tags: + - DBRPs + post: + operationId: PostDBRP + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DBRPCreate' + description: The database retention policy mapping to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/DBRP' + description: Created. Returns the created database retention policy mapping. + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Bad request. The mapping in the request has one or more invalid IDs. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a database retention policy mapping + tags: + - DBRPs + /api/v2/dbrps/{dbrpID}: + delete: + operationId: DeleteDBRPID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Specifies the organization ID of the mapping + in: query + name: orgID + schema: + type: string + - description: Specifies the organization name of the mapping + in: query + name: org + schema: + type: string + - description: The database retention policy mapping + in: path + name: dbrpID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: if any of the IDs passed is invalid + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a database retention policy + tags: + - DBRPs + get: + operationId: GetDBRPsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Specifies the organization ID of the mapping + in: query + name: orgID + schema: + type: string + - description: Specifies the organization name of the mapping + in: query + name: org + schema: + type: string + - description: The database retention policy mapping ID + in: path + name: dbrpID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/DBRPGet' + description: The database retention policy requested + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: if any of the IDs passed is invalid + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a database retention policy mapping + tags: + - DBRPs + patch: + operationId: PatchDBRPID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Specifies the organization ID of the mapping + in: query + name: orgID + schema: + type: string + - description: Specifies the organization name of the mapping + in: query + name: org + schema: + type: string + - description: The database retention policy mapping. + in: path + name: dbrpID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DBRPUpdate' + description: Database retention policy update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/DBRPGet' + description: An updated mapping + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: if any of the IDs passed is invalid + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The mapping was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a database retention policy mapping + tags: + - DBRPs + /api/v2/delete: + post: + operationId: PostDelete + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Specifies the organization to delete data from. + in: query + name: org + schema: + description: Only points from this organization are deleted. + type: string + - description: Specifies the bucket to delete data from. + in: query + name: bucket + schema: + description: Only points from this bucket are deleted. + type: string + - description: Specifies the organization ID of the resource. + in: query + name: orgID + schema: + type: string + - description: Specifies the bucket ID to delete data from. + in: query + name: bucketID + schema: + description: Only points from this bucket ID are deleted. + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DeletePredicateRequest' + description: Deletes data from an InfluxDB bucket. + required: true + responses: + '204': + description: delete has been accepted + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Invalid request. + '403': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: no token was sent or does not have sufficient permissions. + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: the bucket or organization is not found. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: internal server error + summary: Delete data + tags: + - Delete + /api/v2/flags: + get: + operationId: GetFlags + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Flags' + description: Feature flags for the currently authenticated user + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Return the feature flags for the currently authenticated user + tags: + - Users + /health: + get: + operationId: GetHealth + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/HealthCheck' + description: The instance is healthy + '503': + content: + application/json: + schema: + $ref: '#/components/schemas/HealthCheck' + description: The instance is unhealthy + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + servers: + - url: '' + summary: Get the health of an instance + tags: + - Health + /api/v2/labels: + get: + operationId: GetLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: query + name: orgID + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of labels + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels + tags: + - Labels + post: + operationId: PostLabels + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelCreateRequest' + description: Label to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: Added label + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a label + tags: + - Labels + /api/v2/labels/{labelID}: + delete: + operationId: DeleteLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the label to delete. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Label not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label + tags: + - Labels + get: + operationId: GetLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the label to update. + in: path + name: labelID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: A label + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a label + tags: + - Labels + patch: + operationId: PatchLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the label to update. + in: path + name: labelID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelUpdate' + description: Label update + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: Updated label + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Label not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a label + tags: + - Labels + /legacy/authorizations: + get: + operationId: GetLegacyAuthorizations + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Only show legacy authorizations that belong to a user ID. + in: query + name: userID + schema: + type: string + - description: Only show legacy authorizations that belong to a user name. + in: query + name: user + schema: + type: string + - description: Only show legacy authorizations that belong to an organization ID. + in: query + name: orgID + schema: + type: string + - description: Only show legacy authorizations that belong to a organization name. + in: query + name: org + schema: + type: string + - description: Only show legacy authorizations with a specified token (auth name). + in: query + name: token + schema: + type: string + - description: Only show legacy authorizations with a specified auth ID. + in: query + name: authID + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorizations' + description: A list of legacy authorizations + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: List all legacy authorizations + tags: + - Legacy Authorizations + post: + operationId: PostLegacyAuthorizations + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LegacyAuthorizationPostRequest' + description: Legacy authorization to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + description: Legacy authorization created + '400': + $ref: '#/components/responses/ServerError' + description: Invalid request + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Create a legacy authorization + tags: + - Legacy Authorizations + servers: + - url: /private + /legacy/authorizations/{authID}: + delete: + operationId: DeleteLegacyAuthorizationsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the legacy authorization to delete. + in: path + name: authID + required: true + schema: + type: string + responses: + '204': + description: Legacy authorization deleted + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Delete a legacy authorization + tags: + - Legacy Authorizations + get: + operationId: GetLegacyAuthorizationsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the legacy authorization to get. + in: path + name: authID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + description: Legacy authorization details + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Retrieve a legacy authorization + tags: + - Legacy Authorizations + patch: + operationId: PatchLegacyAuthorizationsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the legacy authorization to update. + in: path + name: authID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationUpdateRequest' + description: Legacy authorization to update + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + description: The active or inactive legacy authorization + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Update a legacy authorization to be active or inactive + tags: + - Legacy Authorizations + servers: + - url: /private + /legacy/authorizations/{authID}/password: + post: + operationId: PostLegacyAuthorizationsIDPassword + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the legacy authorization to update. + in: path + name: authID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PasswordResetBody' + description: New password + required: true + responses: + '204': + description: Legacy authorization password set + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Set a legacy authorization password + tags: + - Legacy Authorizations + servers: + - url: /private + /api/v2/maps/mapToken: + get: + operationId: getMapboxToken + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Token' + description: A temp token for Mapbox + '401': + $ref: '#/components/responses/ServerError' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/ServerError' + /api/v2/me: + get: + operationId: GetMe + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + description: The currently authenticated user. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve the currently authenticated user + tags: + - Users + /api/v2/me/password: + put: + operationId: PutMePassword + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PasswordResetBody' + description: New password + required: true + responses: + '204': + description: Password successfully updated + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unsuccessful authentication + security: + - BasicAuthentication: [] + summary: Update a password + tags: + - Users + /api/v2/notificationEndpoints: + get: + operationId: GetNotificationEndpoints + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - description: >- + Only show notification endpoints that belong to specific + organization ID. + in: query + name: orgID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationEndpoints' + description: A list of notification endpoints + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all notification endpoints + tags: + - NotificationEndpoints + post: + operationId: CreateNotificationEndpoint + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PostNotificationEndpoint' + description: Notification endpoint to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationEndpoint' + description: Notification endpoint created + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a notification endpoint + tags: + - NotificationEndpoints + /api/v2/notificationEndpoints/{endpointID}: + delete: + operationId: DeleteNotificationEndpointsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification endpoint ID. + in: path + name: endpointID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The endpoint was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a notification endpoint + tags: + - NotificationEndpoints + get: + operationId: GetNotificationEndpointsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification endpoint ID. + in: path + name: endpointID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationEndpoint' + description: The notification endpoint requested + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a notification endpoint + tags: + - NotificationEndpoints + patch: + operationId: PatchNotificationEndpointsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification endpoint ID. + in: path + name: endpointID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationEndpointUpdate' + description: Check update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationEndpoint' + description: An updated notification endpoint + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The notification endpoint was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a notification endpoint + tags: + - NotificationEndpoints + put: + operationId: PutNotificationEndpointsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification endpoint ID. + in: path + name: endpointID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationEndpoint' + description: A new notification endpoint to replace the existing endpoint with + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationEndpoint' + description: An updated notification endpoint + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The notification endpoint was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a notification endpoint + tags: + - NotificationEndpoints + /api/v2/notificationEndpoints/{endpointID}/labels: + get: + operationId: GetNotificationEndpointsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification endpoint ID. + in: path + name: endpointID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a notification endpoint + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a notification endpoint + tags: + - NotificationEndpoints + post: + operationId: PostNotificationEndpointIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification endpoint ID. + in: path + name: endpointID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The label was added to the notification endpoint + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a notification endpoint + tags: + - NotificationEndpoints + /api/v2/notificationEndpoints/{endpointID}/labels/{labelID}: + delete: + operationId: DeleteNotificationEndpointsIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification endpoint ID. + in: path + name: endpointID + required: true + schema: + type: string + - description: The ID of the label to delete. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Endpoint or label not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label from a notification endpoint + tags: + - NotificationEndpoints + /api/v2/notificationRules: + get: + operationId: GetNotificationRules + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - description: >- + Only show notification rules that belong to a specific organization + ID. + in: query + name: orgID + required: true + schema: + type: string + - description: Only show notifications that belong to the specific check ID. + in: query + name: checkID + schema: + type: string + - description: >- + Only return notification rules that "would match" statuses which + contain the tag key value pairs provided. + in: query + name: tag + schema: + example: env:prod + pattern: ^[a-zA-Z0-9_]+:[a-zA-Z0-9_]+$ + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationRules' + description: A list of notification rules + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all notification rules + tags: + - NotificationRules + post: + operationId: CreateNotificationRule + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PostNotificationRule' + description: Notification rule to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationRule' + description: Notification rule created + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a notification rule + tags: + - NotificationRules + /api/v2/notificationRules/{ruleID}: + delete: + operationId: DeleteNotificationRulesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification rule ID. + in: path + name: ruleID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The check was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a notification rule + tags: + - NotificationRules + get: + operationId: GetNotificationRulesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification rule ID. + in: path + name: ruleID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationRule' + description: The notification rule requested + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a notification rule + tags: + - NotificationRules + patch: + operationId: PatchNotificationRulesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification rule ID. + in: path + name: ruleID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationRuleUpdate' + description: Notification rule update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationRule' + description: An updated notification rule + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The notification rule was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a notification rule + tags: + - NotificationRules + put: + operationId: PutNotificationRulesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification rule ID. + in: path + name: ruleID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationRule' + description: Notification rule update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationRule' + description: An updated notification rule + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The notification rule was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a notification rule + tags: + - NotificationRules + /api/v2/notificationRules/{ruleID}/labels: + get: + operationId: GetNotificationRulesIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification rule ID. + in: path + name: ruleID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a notification rule + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a notification rule + tags: + - NotificationRules + post: + operationId: PostNotificationRuleIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification rule ID. + in: path + name: ruleID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The label was added to the notification rule + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a notification rule + tags: + - NotificationRules + /api/v2/notificationRules/{ruleID}/labels/{labelID}: + delete: + operationId: DeleteNotificationRulesIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification rule ID. + in: path + name: ruleID + required: true + schema: + type: string + - description: The ID of the label to delete. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Rule or label not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete label from a notification rule + tags: + - NotificationRules + /api/v2/notificationRules/{ruleID}/query: + get: + operationId: GetNotificationRulesIDQuery + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification rule ID. + in: path + name: ruleID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/FluxResponse' + description: The notification rule query requested + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Invalid request + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Notification rule not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a notification rule query + tags: + - Rules + /api/v2/orgs: + get: + operationId: GetOrgs + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/Descending' + - description: Filter organizations to a specific organization name. + in: query + name: org + schema: + type: string + - description: Filter organizations to a specific organization ID. + in: query + name: orgID + schema: + type: string + - description: Filter organizations to a specific user ID. + in: query + name: userID + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Organizations' + description: A list of organizations + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all organizations + tags: + - Organizations + post: + operationId: PostOrgs + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PostOrganizationRequest' + description: Organization to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Organization' + description: Organization created + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create an organization + tags: + - Organizations + /api/v2/orgs/{orgID}: + delete: + operationId: DeleteOrgsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the organization to delete. + in: path + name: orgID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Organization not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete an organization + tags: + - Organizations + get: + operationId: GetOrgsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the organization to get. + in: path + name: orgID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Organization' + description: Organization details + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve an organization + tags: + - Organizations + patch: + operationId: PatchOrgsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the organization to get. + in: path + name: orgID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PatchOrganizationRequest' + description: Organization update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Organization' + description: Organization updated + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update an organization + tags: + - Organizations + /api/v2/orgs/{orgID}/members: + get: + operationId: GetOrgsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMembers' + description: A list of organization members + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Organization not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all members of an organization + tags: + - Organizations + post: + operationId: PostOrgsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as member + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMember' + description: Added to organization created + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a member to an organization + tags: + - Organizations + /api/v2/orgs/{orgID}/members/{userID}: + delete: + operationId: DeleteOrgsIDMembersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the member to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + responses: + '204': + description: Member removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove a member from an organization + tags: + - Organizations + /api/v2/orgs/{orgID}/owners: + get: + operationId: GetOrgsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwners' + description: A list of organization owners + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Organization not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all owners of an organization + tags: + - Organizations + post: + operationId: PostOrgsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as owner + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwner' + description: Organization owner added + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add an owner to an organization + tags: + - Organizations + /api/v2/orgs/{orgID}/owners/{userID}: + delete: + operationId: DeleteOrgsIDOwnersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the owner to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + responses: + '204': + description: Owner removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove an owner from an organization + tags: + - Organizations + /api/v2/orgs/{orgID}/secrets: + get: + operationId: GetOrgsIDSecrets + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SecretKeysResponse' + description: A list of all secret keys + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all secret keys for an organization + tags: + - Secrets + patch: + operationId: PatchOrgsIDSecrets + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Secrets' + description: Secret key value pairs to update/add + required: true + responses: + '204': + description: Keys successfully patched + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update secrets in an organization + tags: + - Secrets + /api/v2/orgs/{orgID}/secrets/{secretID}: + delete: + operationId: DeleteOrgsIDSecretsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + - description: The secret ID. + in: path + name: secretID + required: true + schema: + type: string + responses: + '204': + description: Keys successfully deleted + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Delete a secret from an organization + tags: + - Secrets + /api/v2/orgs/{orgID}/secrets/delete: + post: + deprecated: true + operationId: PostOrgsIDSecrets + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SecretKeys' + description: Secret key to delete + required: true + responses: + '204': + description: Keys successfully patched + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete secrets from an organization + tags: + - Secrets + /ping: + get: + operationId: GetPing + responses: + '204': + description: OK + headers: + X-Influxdb-Build: + description: The type of InfluxDB build. + schema: + type: string + X-Influxdb-Version: + description: The version of InfluxDB. + schema: + type: integer + servers: + - url: '' + summary: Checks the status of InfluxDB instance and version of InfluxDB. + tags: + - Ping + head: + operationId: HeadPing + responses: + '204': + description: OK + headers: + X-Influxdb-Build: + description: The type of InfluxDB build. + schema: + type: string + X-Influxdb-Version: + description: The version of InfluxDB. + schema: + type: integer + servers: + - url: '' + summary: Checks the status of InfluxDB instance and version of InfluxDB. + tags: + - Ping + /api/v2/query: + post: + description: > + Retrieves data from InfluxDB buckets. + + + To query data, you need the following: + + - **organization** – _See [View + organizations](https://docs.influxdata.com/influxdb/v2.0/organizations/view-orgs/#view-your-organization-id) + for instructions on viewing your organization ID._ + + - **API token** – _See [View + tokens](https://docs.influxdata.com/influxdb/v2.0/security/tokens/view-tokens/) + for instructions on viewing your API token._ + - **InfluxDB URL** – _See [InfluxDB + URLs](https://docs.influxdata.com/influxdb/v2.0/reference/urls/)_. + + - **Flux query** – _See [Flux](https://docs.influxdata.com/flux/v0.x/)._ + + + For more information and examples, see [Query with the InfluxDB + API](https://docs.influxdata.com/influxdb/v2.0/query-data/execute-queries/influx-api/). + operationId: PostQuery + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: >- + The Accept-Encoding request HTTP header advertises which content + encoding, usually a compression algorithm, the client is able to + understand. + in: header + name: Accept-Encoding + schema: + default: identity + description: >- + Specifies that the query response in the body should be encoded + with gzip or not encoded with identity. + enum: + - gzip + - identity + type: string + - in: header + name: Content-Type + schema: + enum: + - application/json + - application/vnd.flux + type: string + - description: >- + Specifies the name of the organization executing the query. Takes + either the ID or Name. If both `orgID` and `org` are specified, + `org` takes precedence. + in: query + name: org + schema: + type: string + - description: >- + Specifies the ID of the organization executing the query. If both + `orgID` and `org` are specified, `org` takes precedence. + in: query + name: orgID + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + application/vnd.flux: + example: | + from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "example-measurement") + schema: + type: string + description: Flux query or specification to execute + responses: + '200': + content: + application/vnd.influx.arrow: + schema: + format: binary + type: string + text/csv: + schema: + example: > + result,table,_start,_stop,_time,region,host,_value + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 + type: string + description: Success. Returns query results. + headers: + Content-Encoding: + description: >- + The Content-Encoding entity header is used to compress the + media-type. When present, its value indicates which encodings + were applied to the entity-body + schema: + default: identity + description: >- + Specifies that the response in the body is encoded with gzip + or not encoded with identity. + enum: + - gzip + - identity + type: string + Trace-Id: + description: >- + The Trace-Id header reports the request's trace ID, if one was + generated. + schema: + description: Specifies the request's trace ID. + type: string + '429': + description: >- + Token is temporarily over quota. The Retry-After header describes + when to try the read again. + headers: + Retry-After: + description: >- + A non-negative decimal integer indicating the seconds to delay + after the response is received. + schema: + format: int32 + type: integer + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Error processing query + summary: Query data + tags: + - Query + /api/v2/query/analyze: + post: + operationId: PostQueryAnalyze + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: header + name: Content-Type + schema: + enum: + - application/json + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + description: Flux query to analyze + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/AnalyzeQueryResponse' + description: Query analyze results. Errors will be empty if the query is valid. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Internal server error + headers: + X-Influx-Error: + description: Error string describing the problem + schema: + type: string + X-Influx-Reference: + description: Reference code unique to the error type + schema: + type: integer + summary: Analyze a Flux query + tags: + - Query + /api/v2/query/ast: + post: + description: Analyzes flux query and generates a query specification. + operationId: PostQueryAst + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: header + name: Content-Type + schema: + enum: + - application/json + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LanguageRequest' + description: Analyzed Flux query to generate abstract syntax tree. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ASTResponse' + description: Abstract syntax tree of the flux query. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Any response other than 200 is an internal server error + summary: Generate an Abstract Syntax Tree (AST) from a query + tags: + - Query + /api/v2/query/suggestions: + get: + operationId: GetQuerySuggestions + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/FluxSuggestions' + description: Suggestions for next functions in call chain + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Any response other than 200 is an internal server error + summary: Retrieve query suggestions + tags: + - Query + /api/v2/query/suggestions/{name}: + get: + operationId: GetQuerySuggestionsName + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The name of the branching suggestion. + in: path + name: name + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/FluxSuggestion' + description: Suggestions for next functions in call chain + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Any response other than 200 is an internal server error + summary: Retrieve query suggestions for a branching suggestion + tags: + - Query + /ready: + get: + operationId: GetReady + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Ready' + description: The instance is ready + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + servers: + - url: '' + summary: Get the readiness of an instance at startup + tags: + - Ready + /api/v2/resources: + get: + operationId: GetResources + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/json: + schema: + items: + type: string + type: array + description: All resources targets + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Internal server error + summary: List all known resources + tags: + - Resources + /api/v2/restore/bucket/{bucketID}: + post: + deprecated: true + operationId: PostRestoreBucketID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + - in: header + name: Content-Type + schema: + default: application/octet-stream + enum: + - application/octet-stream + type: string + requestBody: + content: + text/plain: + schema: + format: byte + type: string + description: Database info serialized as protobuf. + required: true + responses: + '200': + content: + application/json: + schema: + format: byte + type: string + description: ID mappings for shards in bucket. + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Overwrite storage metadata for a bucket with shard info from a backup. + tags: + - Restore + /api/v2/restore/bucketMetadata: + post: + operationId: PostRestoreBucketMetadata + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/BucketMetadataManifest' + description: Metadata manifest for a bucket. + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/RestoredBucketMappings' + description: ID mappings for shards in new bucket. + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Create a new bucket pre-seeded with shard info from a backup. + tags: + - Restore + /api/v2/restore/kv: + post: + operationId: PostRestoreKV + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: >- + When present, its value indicates to the database that compression + is applied to the line-protocol body. + in: header + name: Content-Encoding + schema: + default: identity + description: >- + Specifies that the line protocol in the body is encoded with gzip + or not encoded with identity. + enum: + - gzip + - identity + type: string + - in: header + name: Content-Type + schema: + default: application/octet-stream + enum: + - application/octet-stream + type: string + requestBody: + content: + text/plain: + schema: + format: binary + type: string + description: Full KV snapshot. + required: true + responses: + '200': + content: + application/json: + schema: + properties: + token: + description: >- + token is the root token for the instance after restore + (this is overwritten during the restore) type: string type: object - type: array - type: object - errors: - items: - properties: - fields: - items: - type: string - type: array - indexes: - items: - type: integer - type: array - kind: - $ref: '#/components/schemas/TemplateKind' - reason: - type: string - type: object - type: array - sources: - items: + description: KV store successfully overwritten. + '204': + description: KV store successfully overwritten. + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Overwrite the embedded KV store on the server with a backed-up snapshot. + tags: + - Restore + /api/v2/restore/shards/{shardID}: + post: + operationId: PostRestoreShardId + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: >- + When present, its value indicates to the database that compression + is applied to the line-protocol body. + in: header + name: Content-Encoding + schema: + default: identity + description: >- + Specifies that the line protocol in the body is encoded with gzip + or not encoded with identity. + enum: + - gzip + - identity + type: string + - in: header + name: Content-Type + schema: + default: application/octet-stream + enum: + - application/octet-stream + type: string + - description: The shard ID. + in: path + name: shardID + required: true + schema: + type: string + requestBody: + content: + text/plain: + schema: + format: binary + type: string + description: TSM snapshot. + required: true + responses: + '204': + description: TSM snapshot successfully restored. + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Restore a TSM snapshot into a shard. + tags: + - Restore + /api/v2/restore/sql: + post: + operationId: PostRestoreSQL + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: >- + When present, its value indicates to the database that compression + is applied to the line-protocol body. + in: header + name: Content-Encoding + schema: + default: identity + description: >- + Specifies that the line protocol in the body is encoded with gzip + or not encoded with identity. + enum: + - gzip + - identity + type: string + - in: header + name: Content-Type + schema: + default: application/octet-stream + enum: + - application/octet-stream + type: string + requestBody: + content: + text/plain: + schema: + format: binary + type: string + description: Full SQL snapshot. + required: true + responses: + '204': + description: SQL store successfully overwritten. + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: >- + Overwrite the embedded SQL store on the server with a backed-up + snapshot. + tags: + - Restore + /api/v2/scrapers: + get: + operationId: GetScrapers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Specifies the name of the scraper target. + in: query + name: name + schema: + type: string + - description: >- + List of scraper target IDs to return. If both `id` and `owner` are + specified, only `id` is used. + in: query + name: id + schema: + items: + type: string + type: array + - description: Specifies the organization ID of the scraper target. + in: query + name: orgID + schema: + type: string + - description: Specifies the organization name of the scraper target. + in: query + name: org + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ScraperTargetResponses' + description: All scraper targets + summary: List all scraper targets + tags: + - Scraper Targets + post: + operationId: PostScrapers + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScraperTargetRequest' + description: Scraper target to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ScraperTargetResponse' + description: Scraper target created + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Internal server error + summary: Create a scraper target + tags: + - Scraper Targets + /api/v2/scrapers/{scraperTargetID}: + delete: + operationId: DeleteScrapersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The identifier of the scraper target. + in: path + name: scraperTargetID + required: true + schema: + type: string + responses: + '204': + description: Scraper target deleted + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Internal server error + summary: Delete a scraper target + tags: + - Scraper Targets + get: + operationId: GetScrapersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The identifier of the scraper target. + in: path + name: scraperTargetID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ScraperTargetResponse' + description: The scraper target + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Internal server error + summary: Retrieve a scraper target + tags: + - Scraper Targets + patch: + operationId: PatchScrapersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The identifier of the scraper target. + in: path + name: scraperTargetID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScraperTargetRequest' + description: Scraper target update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ScraperTargetResponse' + description: Scraper target updated + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Internal server error + summary: Update a scraper target + tags: + - Scraper Targets + /api/v2/scrapers/{scraperTargetID}/labels: + get: + operationId: GetScrapersIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of labels for a scraper target. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a scraper target + tags: + - Scraper Targets + post: + operationId: PostScrapersIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The newly added label + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a scraper target + tags: + - Scraper Targets + /api/v2/scrapers/{scraperTargetID}/labels/{labelID}: + delete: + operationId: DeleteScrapersIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + - description: The label ID. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Scraper target not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label from a scraper target + tags: + - Scraper Targets + /api/v2/scrapers/{scraperTargetID}/members: + get: + operationId: GetScrapersIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMembers' + description: A list of scraper target members + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all users with member privileges for a scraper target + tags: + - Scraper Targets + post: + operationId: PostScrapersIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as member + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMember' + description: Member added to scraper targets + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a member to a scraper target + tags: + - Scraper Targets + /api/v2/scrapers/{scraperTargetID}/members/{userID}: + delete: + operationId: DeleteScrapersIDMembersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of member to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + responses: + '204': + description: Member removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove a member from a scraper target + tags: + - Scraper Targets + /api/v2/scrapers/{scraperTargetID}/owners: + get: + operationId: GetScrapersIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwners' + description: A list of scraper target owners + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all owners of a scraper target + tags: + - Scraper Targets + post: + operationId: PostScrapersIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as owner + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwner' + description: Scraper target owner added + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add an owner to a scraper target + tags: + - Scraper Targets + /api/v2/scrapers/{scraperTargetID}/owners/{userID}: + delete: + operationId: DeleteScrapersIDOwnersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of owner to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + responses: + '204': + description: Owner removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove an owner from a scraper target + tags: + - Scraper Targets + /api/v2/setup: + get: + description: >- + Returns `true` if no default user, organization, or bucket has been + created. + operationId: GetSetup + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/IsOnboarding' + description: allowed true or false + summary: Check if database has default user, org, bucket + tags: + - Setup + post: + description: Post an onboarding request to set up initial user, org and bucket. + operationId: PostSetup + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/OnboardingRequest' + description: Source to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/OnboardingResponse' + description: Created default user, bucket, org + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Set up initial user, org and bucket + tags: + - Setup + /api/v2/signin: + post: + description: >- + Authenticates ***Basic Auth*** credentials for a user. If successful, + creates a new UI session for the user. + operationId: PostSignin + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '204': + description: Success. User authenticated. + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unauthorized access. + '403': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: User account is disabled. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unsuccessful authentication. + security: + - BasicAuthentication: [] + summary: Create a user session. + tags: + - Signin + /api/v2/signout: + post: + description: Expires the current UI session for the user. + operationId: PostSignout + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '204': + description: Session successfully expired + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unauthorized access + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unsuccessful session expiry + summary: Expire the current UI session + tags: + - Signout + /api/v2/sources: + get: + operationId: GetSources + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The name of the organization. + in: query + name: org + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Sources' + description: A list of sources + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all sources + tags: + - Sources + post: + operationId: PostSources + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Source' + description: Source to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Source' + description: Created Source + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a source + tags: + - Sources + /api/v2/sources/{sourceID}: + delete: + operationId: DeleteSourcesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The source ID. + in: path + name: sourceID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: View not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a source + tags: + - Sources + get: + operationId: GetSourcesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The source ID. + in: path + name: sourceID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Source' + description: A source + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Source not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a source + tags: + - Sources + patch: + operationId: PatchSourcesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The source ID. + in: path + name: sourceID + required: true + schema: type: string - type: array - stackID: - type: string - summary: - properties: - buckets: - items: - properties: - description: - type: string - envReferences: - $ref: '#/components/schemas/TemplateEnvReferences' - id: - type: string - kind: - $ref: '#/components/schemas/TemplateKind' - labelAssociations: - items: - $ref: '#/components/schemas/TemplateSummaryLabel' - type: array - name: - type: string - orgID: - type: string - retentionPeriod: - type: integer - templateMetaName: - type: string - type: object - type: array - checks: - items: - allOf: - - $ref: '#/components/schemas/CheckDiscriminator' - - properties: - envReferences: - $ref: '#/components/schemas/TemplateEnvReferences' - kind: - $ref: '#/components/schemas/TemplateKind' - labelAssociations: - items: - $ref: '#/components/schemas/TemplateSummaryLabel' - type: array - templateMetaName: - type: string - type: object - type: array - dashboards: - items: - properties: - charts: - items: - $ref: '#/components/schemas/TemplateChart' - type: array - description: - type: string - envReferences: - $ref: '#/components/schemas/TemplateEnvReferences' - id: - type: string - kind: - $ref: '#/components/schemas/TemplateKind' - labelAssociations: - items: - $ref: '#/components/schemas/TemplateSummaryLabel' - type: array - name: - type: string - orgID: - type: string - templateMetaName: - type: string - type: object - type: array - labelMappings: - items: - properties: - labelID: - type: string - labelName: - type: string - labelTemplateMetaName: - type: string - resourceID: - type: string - resourceName: - type: string - resourceTemplateMetaName: - type: string - resourceType: - type: string - status: - type: string - type: object - type: array - labels: - items: - $ref: '#/components/schemas/TemplateSummaryLabel' - type: array - missingEnvRefs: - items: - type: string - type: array - missingSecrets: - items: - type: string - type: array - notificationEndpoints: - items: - allOf: - - $ref: '#/components/schemas/NotificationEndpointDiscriminator' - - properties: - envReferences: - $ref: '#/components/schemas/TemplateEnvReferences' - kind: - $ref: '#/components/schemas/TemplateKind' - labelAssociations: - items: - $ref: '#/components/schemas/TemplateSummaryLabel' - type: array - templateMetaName: - type: string - type: object - type: array - notificationRules: - items: - properties: - description: - type: string - endpointID: - type: string - endpointTemplateMetaName: - type: string - endpointType: - type: string - envReferences: - $ref: '#/components/schemas/TemplateEnvReferences' - every: - type: string - kind: - $ref: '#/components/schemas/TemplateKind' - labelAssociations: - items: - $ref: '#/components/schemas/TemplateSummaryLabel' - type: array - messageTemplate: - type: string - name: - type: string - offset: - type: string - status: - type: string - statusRules: - items: - properties: - currentLevel: - type: string - previousLevel: - type: string - type: object - type: array - tagRules: - items: - properties: - key: - type: string - operator: - type: string - value: - type: string - type: object - type: array - templateMetaName: - type: string - type: object - type: array - tasks: - items: - properties: - cron: - type: string - description: - type: string - envReferences: - $ref: '#/components/schemas/TemplateEnvReferences' - every: - type: string - id: - type: string - kind: - $ref: '#/components/schemas/TemplateKind' - name: - type: string - offset: - type: string - query: - type: string - status: - type: string - templateMetaName: - type: string - type: object - type: array - telegrafConfigs: - items: - allOf: - - $ref: '#/components/schemas/TelegrafRequest' - - properties: - envReferences: - $ref: '#/components/schemas/TemplateEnvReferences' - kind: - $ref: '#/components/schemas/TemplateKind' - labelAssociations: - items: - $ref: '#/components/schemas/TemplateSummaryLabel' - type: array - templateMetaName: - type: string - type: object - type: array - variables: - items: + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Source' + description: Source update + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Source' + description: Created Source + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Source not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a Source + tags: + - Sources + /api/v2/sources/{sourceID}/buckets: + get: + operationId: GetSourcesIDBuckets + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The source ID. + in: path + name: sourceID + required: true + schema: + type: string + - description: The name of the organization. + in: query + name: org + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Buckets' + description: A source + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Source not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Get buckets in a source + tags: + - Sources + - Buckets + /api/v2/sources/{sourceID}/health: + get: + operationId: GetSourcesIDHealth + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The source ID. + in: path + name: sourceID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/HealthCheck' + description: The source is healthy + '503': + content: + application/json: + schema: + $ref: '#/components/schemas/HealthCheck' + description: The source is not healthy + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Get the health of a source + tags: + - Sources + /api/v2/stacks: + get: + operationId: ListStacks + parameters: + - description: The organization ID of the stacks + in: query + name: orgID + required: true + schema: + type: string + - description: A collection of names to filter the list by. + in: query + name: name + schema: + type: string + - description: A collection of stackIDs to filter the list by. + in: query + name: stackID + schema: + type: string + responses: + '200': + content: + application/json: + schema: properties: - arguments: - $ref: '#/components/schemas/VariableProperties' - description: - type: string - envReferences: - $ref: '#/components/schemas/TemplateEnvReferences' - id: - type: string - kind: - $ref: '#/components/schemas/TemplateKind' - labelAssociations: + stacks: items: - $ref: '#/components/schemas/TemplateSummaryLabel' + $ref: '#/components/schemas/Stack' type: array - name: - type: string - orgID: - type: string - templateMetaName: - type: string type: object - type: array - type: object - type: object - TemplateSummaryLabel: - properties: - envReferences: - $ref: '#/components/schemas/TemplateEnvReferences' - id: - type: string - kind: - $ref: '#/components/schemas/TemplateKind' - name: - type: string - orgID: - type: string - properties: - properties: - color: - type: string - description: - type: string - type: object - templateMetaName: - type: string - type: object - TestStatement: - description: Declares a Flux test case - properties: - assignment: - $ref: '#/components/schemas/VariableAssignment' - type: - $ref: '#/components/schemas/NodeType' - type: object - Threshold: - discriminator: - mapping: - greater: '#/components/schemas/GreaterThreshold' - lesser: '#/components/schemas/LesserThreshold' - range: '#/components/schemas/RangeThreshold' - propertyName: type - oneOf: - - $ref: '#/components/schemas/GreaterThreshold' - - $ref: '#/components/schemas/LesserThreshold' - - $ref: '#/components/schemas/RangeThreshold' - ThresholdBase: - properties: - allValues: - description: If true, only alert if all values meet threshold. - type: boolean - level: - $ref: '#/components/schemas/CheckStatusLevel' - ThresholdCheck: - allOf: - - $ref: '#/components/schemas/CheckBase' - - properties: - every: - description: Check repetition interval. - type: string - offset: - description: Duration to delay after the schedule, before executing check. - type: string - statusMessageTemplate: - description: The template used to generate and write a status message. - type: string - tags: - description: List of tags to write to each status. - items: - properties: - key: + description: Success. Returns the list of stacks. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List installed templates + tags: + - Templates + post: + operationId: CreateStack + requestBody: + content: + application/json: + schema: + properties: + description: + type: string + name: + type: string + orgID: + type: string + urls: + items: type: string - value: + type: array + title: PostStackRequest + type: object + description: The stack to create. + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Stack' + description: Success. Returns the newly created stack. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a new stack + tags: + - Templates + /api/v2/stacks/{stack_id}: + delete: + operationId: DeleteStack + parameters: + - description: The identifier of the stack. + in: path + name: stack_id + required: true + schema: + type: string + - description: The identifier of the organization. + in: query + name: orgID + required: true + schema: + type: string + responses: + '204': + description: The stack and its associated resources were deleted. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a stack and associated resources + tags: + - Templates + get: + operationId: ReadStack + parameters: + - description: The identifier of the stack. + in: path + name: stack_id + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Stack' + description: Returns the stack. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a stack + tags: + - Templates + patch: + operationId: UpdateStack + parameters: + - description: The identifier of the stack. + in: path + name: stack_id + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + properties: + additionalResources: + items: + properties: + kind: + type: string + resourceID: + type: string + templateMetaName: + type: string + required: + - kind + - resourceID + type: object + type: array + description: + nullable: true + type: string + name: + nullable: true + type: string + templateURLs: + items: type: string - type: object - type: array - thresholds: - items: - $ref: '#/components/schemas/Threshold' - type: array - type: - enum: - - threshold - type: string - required: - - type - type: object - Token: - properties: - token: - type: string - type: object - UnaryExpression: - description: Uses operators to act on a single operand in an expression - properties: - argument: - $ref: '#/components/schemas/Expression' - operator: - type: string - type: - $ref: '#/components/schemas/NodeType' - type: object - UnsignedIntegerLiteral: - description: Represents integer numbers - properties: - type: - $ref: '#/components/schemas/NodeType' - value: - type: string - type: object - User: - properties: - id: - readOnly: true - type: string - name: - type: string - oauthID: - type: string - status: - default: active - description: If inactive the user is inactive. - enum: - - active - - inactive - type: string - required: - - name - UserResponse: - properties: - id: - readOnly: true - type: string - links: - example: - self: /api/v2/users/1 - properties: - self: - format: uri - type: string - readOnly: true - type: object - name: - type: string - oauthID: - type: string - status: - default: active - description: If inactive the user is inactive. - enum: - - active - - inactive - type: string - required: - - name - Users: - properties: - links: - properties: - self: - format: uri - type: string - type: object - users: - items: - $ref: '#/components/schemas/UserResponse' - type: array - type: object - Variable: - properties: - arguments: - $ref: '#/components/schemas/VariableProperties' - createdAt: - format: date-time - type: string - description: - type: string - id: - readOnly: true - type: string - labels: - $ref: '#/components/schemas/Labels' - links: - properties: - labels: - format: uri - type: string - org: - format: uri - type: string - self: - format: uri - type: string - readOnly: true - type: object - name: - type: string - orgID: - type: string - selected: - items: + nullable: true + type: array + title: PatchStackRequest + type: object + description: The stack to update. + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Stack' + description: Returns the updated stack. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a stack + tags: + - Templates + /api/v2/stacks/{stack_id}/uninstall: + post: + operationId: UninstallStack + parameters: + - description: The identifier of the stack. + in: path + name: stack_id + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Stack' + description: Returns the uninstalled stack. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Uninstall a stack + tags: + - Templates + /api/v2/tasks: + get: + operationId: GetTasks + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Returns task with a specific name. + in: query + name: name + schema: + type: string + - description: Return tasks after a specified ID. + in: query + name: after + schema: + type: string + - description: Filter tasks to a specific user ID. + in: query + name: user + schema: + type: string + - description: Filter tasks to a specific organization name. + in: query + name: org + schema: + type: string + - description: Filter tasks to a specific organization ID. + in: query + name: orgID + schema: + type: string + - description: Filter tasks by a status--"inactive" or "active". + in: query + name: status + schema: + enum: + - active + - inactive + type: string + - description: The number of tasks to return + in: query + name: limit + schema: + default: 100 + maximum: 500 + minimum: 1 + type: integer + - description: Type of task, unset by default. + in: query + name: type + required: false + schema: + default: '' + enum: + - basic + - system + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Tasks' + description: A list of tasks + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all tasks + tags: + - Tasks + post: + operationId: PostTasks + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TaskCreateRequest' + description: Task to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + description: Task created + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a new task + tags: + - Tasks + /api/v2/tasks/{taskID}: + delete: + description: Deletes a task and all associated records + operationId: DeleteTasksID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the task to delete. + in: path + name: taskID + required: true + schema: + type: string + responses: + '204': + description: Task deleted + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a task + tags: + - Tasks + get: + operationId: GetTasksID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + description: Task details + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a task + tags: + - Tasks + patch: + description: Update a task. This will cancel all queued runs. + operationId: PatchTasksID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TaskUpdateRequest' + description: Task update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + description: Task updated + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a task + tags: + - Tasks + /api/v2/tasks/{taskID}/labels: + get: + operationId: GetTasksIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a task + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a task + tags: + - Tasks + post: + operationId: PostTasksIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: A list of all labels for a task + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a task + tags: + - Tasks + /api/v2/tasks/{taskID}/labels/{labelID}: + delete: + operationId: DeleteTasksIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + - description: The label ID. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Task not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label from a task + tags: + - Tasks + /api/v2/tasks/{taskID}/logs: + get: + operationId: GetTasksIDLogs + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Logs' + description: All logs for a task + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve all logs for a task + tags: + - Tasks + /api/v2/tasks/{taskID}/members: + get: + operationId: GetTasksIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMembers' + description: A list of users who have member privileges for a task + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all task members + tags: + - Tasks + post: + operationId: PostTasksIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as member + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMember' + description: Added to task members + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a member to a task + tags: + - Tasks + /api/v2/tasks/{taskID}/members/{userID}: + delete: + operationId: DeleteTasksIDMembersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the member to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '204': + description: Member removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove a member from a task + tags: + - Tasks + /api/v2/tasks/{taskID}/owners: + get: + operationId: GetTasksIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwners' + description: A list of users who have owner privileges for a task + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all owners of a task + tags: + - Tasks + post: + operationId: PostTasksIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as owner + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwner' + description: Added to task owners + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add an owner to a task + tags: + - Tasks + /api/v2/tasks/{taskID}/owners/{userID}: + delete: + operationId: DeleteTasksIDOwnersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the owner to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '204': + description: Owner removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove an owner from a task + tags: + - Tasks + /api/v2/tasks/{taskID}/runs: + get: + operationId: GetTasksIDRuns + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the task to get runs for. + in: path + name: taskID + required: true + schema: + type: string + - description: Returns runs after a specific ID. + in: query + name: after + schema: + type: string + - description: The number of runs to return + in: query + name: limit + schema: + default: 100 + maximum: 500 + minimum: 1 + type: integer + - description: Filter runs to those scheduled after this time, RFC3339 + in: query + name: afterTime + schema: + format: date-time + type: string + - description: Filter runs to those scheduled before this time, RFC3339 + in: query + name: beforeTime + schema: + format: date-time + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Runs' + description: A list of task runs + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List runs for a task + tags: + - Tasks + post: + operationId: PostTasksIDRuns + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: taskID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RunManually' + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Run' + description: Run scheduled to start + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Manually start a task run, overriding the current schedule + tags: + - Tasks + /api/v2/tasks/{taskID}/runs/{runID}: + delete: + operationId: DeleteTasksIDRunsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + - description: The run ID. + in: path + name: runID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Cancel a running task + tags: + - Tasks + get: + operationId: GetTasksIDRunsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + - description: The run ID. + in: path + name: runID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Run' + description: The run record + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a single run for a task + tags: + - Tasks + /api/v2/tasks/{taskID}/runs/{runID}/logs: + get: + operationId: GetTasksIDRunsIDLogs + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: ID of task to get logs for. + in: path + name: taskID + required: true + schema: + type: string + - description: ID of run to get logs for. + in: path + name: runID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Logs' + description: All logs for a run + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve all logs for a run + tags: + - Tasks + /api/v2/tasks/{taskID}/runs/{runID}/retry: + post: + operationId: PostTasksIDRunsIDRetry + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + - description: The run ID. + in: path + name: runID + required: true + schema: + type: string + requestBody: + content: + application/json; charset=utf-8: + schema: + type: object + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Run' + description: Run that has been queued + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retry a task run + tags: + - Tasks + /api/v2/telegraf/plugins: + get: + operationId: GetTelegrafPlugins + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The type of plugin desired. + in: query + name: type + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/TelegrafPlugins' + description: A list of Telegraf plugins. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all Telegraf plugins + tags: + - Telegraf Plugins + /api/v2/telegrafs: + get: + operationId: GetTelegrafs + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID the Telegraf config belongs to. + in: query + name: orgID + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Telegrafs' + description: A list of Telegraf configurations + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all Telegraf configurations + tags: + - Telegrafs + post: + operationId: PostTelegrafs + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TelegrafRequest' + description: Telegraf configuration to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Telegraf' + description: Telegraf configuration created + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a Telegraf configuration + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}: + delete: + operationId: DeleteTelegrafsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf configuration ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a Telegraf configuration + tags: + - Telegrafs + get: + operationId: GetTelegrafsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf configuration ID. + in: path + name: telegrafID + required: true + schema: + type: string + - in: header + name: Accept + required: false + schema: + default: application/toml + enum: + - application/toml + - application/json + - application/octet-stream + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Telegraf' + application/octet-stream: + example: |- + [agent] + interval = "10s" + schema: + type: string + application/toml: + example: |- + [agent] + interval = "10s" + schema: + type: string + description: Telegraf configuration details + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a Telegraf configuration + tags: + - Telegrafs + put: + operationId: PutTelegrafsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TelegrafRequest' + description: Telegraf configuration update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Telegraf' + description: An updated Telegraf configurations + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a Telegraf configuration + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/labels: + get: + operationId: GetTelegrafsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a Telegraf config + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a Telegraf config + tags: + - Telegrafs + post: + operationId: PostTelegrafsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The label added to the Telegraf config + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a Telegraf config + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/labels/{labelID}: + delete: + operationId: DeleteTelegrafsIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + - description: The label ID. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Telegraf config not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label from a Telegraf config + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/members: + get: + operationId: GetTelegrafsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMembers' + description: A list of Telegraf config members + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all users with member privileges for a Telegraf config + tags: + - Telegrafs + post: + operationId: PostTelegrafsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as member + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMember' + description: Member added to Telegraf config + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a member to a Telegraf config + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/members/{userID}: + delete: + operationId: DeleteTelegrafsIDMembersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the member to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '204': + description: Member removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove a member from a Telegraf config + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/owners: + get: + operationId: GetTelegrafsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf configuration ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwners' + description: Returns Telegraf configuration owners as a ResourceOwners list + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all owners of a Telegraf configuration + tags: + - Telegrafs + post: + operationId: PostTelegrafsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf configuration ID. + in: path + name: telegrafID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as owner + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwner' + description: >- + Telegraf configuration owner was added. Returns a ResourceOwner that + references the User. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add an owner to a Telegraf configuration + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/owners/{userID}: + delete: + operationId: DeleteTelegrafsIDOwnersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the owner to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '204': + description: Owner removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove an owner from a Telegraf config + tags: + - Telegrafs + /api/v2/templates/apply: + post: + description: Applies or performs a dry-run of template in an organization. + operationId: ApplyTemplate + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateApply' + application/x-jsonnet: + schema: + $ref: '#/components/schemas/TemplateApply' + text/yml: + schema: + $ref: '#/components/schemas/TemplateApply' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateSummary' + description: > + Success. The package dry-run succeeded. No new resources were + created. Returns a diff and summary of the dry-run. The diff and + summary won't contain IDs for resources that didn't exist at the + time of the dry-run. + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateSummary' + description: > + Success. The package applied successfully. Returns a diff and + summary of the run. The summary contains newly created resources. + The diff compares the initial state to the state after the package + applied. This corresponds to `"dryRun": true`. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Apply or dry-run a template + tags: + - Templates + /api/v2/templates/export: + post: + operationId: ExportTemplate + requestBody: + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/TemplateExportByID' + - $ref: '#/components/schemas/TemplateExportByName' + description: Export resources as an InfluxDB template. + required: false + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Template' + application/x-yaml: + schema: + $ref: '#/components/schemas/Template' + description: >- + The template was created successfully. Returns the newly created + template. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Export a new template + tags: + - Templates + /api/v2/users: + get: + operationId: GetUsers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/After' + - in: query + name: name + schema: + type: string + - in: query + name: id + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Users' + description: A list of users + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: List all users + tags: + - Users + post: + operationId: PostUsers + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/User' + description: User to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + description: User created + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Create a user + tags: + - Users + /api/v2/users/{userID}: + delete: + operationId: DeleteUsersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the user to delete. + in: path + name: userID + required: true + schema: type: string - type: array - updatedAt: - format: date-time - type: string - required: - - name - - orgID - - arguments - type: object - VariableAssignment: - description: Represents the declaration of a variable - properties: - id: - $ref: '#/components/schemas/Identifier' - init: - $ref: '#/components/schemas/Expression' - type: - $ref: '#/components/schemas/NodeType' - type: object - VariableProperties: - oneOf: - - $ref: '#/components/schemas/QueryVariableProperties' - - $ref: '#/components/schemas/ConstantVariableProperties' - - $ref: '#/components/schemas/MapVariableProperties' - type: object - Variables: - example: - variables: - - arguments: - type: constant - values: - - howdy - - hello - - hi - - yo - - oy - id: '1221432' - name: ':ok:' - selected: - - hello - - arguments: - type: map - values: - a: fdjaklfdjkldsfjlkjdsa - b: dfaksjfkljekfajekdljfas - c: fdjksajfdkfeawfeea - id: '1221432' - name: ':ok:' - selected: - - c - - arguments: - language: flux - query: 'from(bucket: "foo") |> showMeasurements()' - type: query - id: '1221432' - name: ':ok:' - selected: - - host - properties: - variables: - items: - $ref: '#/components/schemas/Variable' - type: array - type: object - View: - properties: - id: - readOnly: true - type: string - links: - properties: - self: - type: string - readOnly: true - type: object - name: - type: string - properties: - $ref: '#/components/schemas/ViewProperties' - required: - - name - - properties - ViewProperties: - oneOf: - - $ref: '#/components/schemas/LinePlusSingleStatProperties' - - $ref: '#/components/schemas/XYViewProperties' - - $ref: '#/components/schemas/SingleStatViewProperties' - - $ref: '#/components/schemas/HistogramViewProperties' - - $ref: '#/components/schemas/GaugeViewProperties' - - $ref: '#/components/schemas/TableViewProperties' - - $ref: '#/components/schemas/SimpleTableViewProperties' - - $ref: '#/components/schemas/MarkdownViewProperties' - - $ref: '#/components/schemas/CheckViewProperties' - - $ref: '#/components/schemas/ScatterViewProperties' - - $ref: '#/components/schemas/HeatmapViewProperties' - - $ref: '#/components/schemas/MosaicViewProperties' - - $ref: '#/components/schemas/BandViewProperties' - - $ref: '#/components/schemas/GeoViewProperties' - Views: - properties: - links: - properties: - self: - type: string - type: object - views: - items: - $ref: '#/components/schemas/View' - type: array - type: object - WritePrecision: - enum: - - ms - - s - - us - - ns - type: string - XYGeom: - enum: - - line - - step - - stacked - - bar - - monotoneX - type: string - XYViewProperties: - properties: - axes: - $ref: '#/components/schemas/Axes' - colors: - description: Colors define color encoding of data into a visualization - items: - $ref: '#/components/schemas/DashboardColor' - type: array - generateXAxisTicks: - items: + responses: + '204': + description: User deleted + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Delete a user + tags: + - Users + get: + operationId: GetUsersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The user ID. + in: path + name: userID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + description: User details + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Retrieve a user + tags: + - Users + patch: + operationId: PatchUsersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the user to update. + in: path + name: userID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/User' + description: User update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + description: User updated + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Update a user + tags: + - Users + /api/v2/users/{userID}/password: + post: + operationId: PostUsersIDPassword + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The user ID. + in: path + name: userID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PasswordResetBody' + description: New password + required: true + responses: + '204': + description: Password successfully updated + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unsuccessful authentication + security: + - BasicAuthentication: [] + summary: Update a password + tags: + - Users + /api/v2/variables: + get: + operationId: GetVariables + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The name of the organization. + in: query + name: org + schema: type: string - type: array - generateYAxisTicks: - items: + - description: The organization ID. + in: query + name: orgID + schema: type: string - type: array - geom: - $ref: '#/components/schemas/XYGeom' - hoverDimension: - enum: - - auto - - x - - 'y' - - xy - type: string - legendColorizeRows: - type: boolean - legendHide: - type: boolean - legendOpacity: - format: float - type: number - legendOrientationThreshold: - type: integer - note: - type: string - position: - enum: - - overlaid - - stacked - type: string - queries: - items: - $ref: '#/components/schemas/DashboardQuery' - type: array - shadeBelow: - type: boolean - shape: - enum: - - chronograf-v2 - type: string - showNoteWhenEmpty: - description: If true, will display note when empty - type: boolean - staticLegend: - $ref: '#/components/schemas/StaticLegend' - timeFormat: - type: string - type: - enum: - - xy - type: string - xColumn: - type: string - xTickStart: - format: float - type: number - xTickStep: - format: float - type: number - xTotalTicks: - type: integer - yColumn: - type: string - yTickStart: - format: float - type: number - yTickStep: - format: float - type: number - yTotalTicks: - type: integer - required: - - type - - geom - - queries - - shape - - axes - - colors - - note - - showNoteWhenEmpty - - position - type: object - responses: - ServerError: - content: - application/json: + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Variables' + description: A list of variables for an organization + '400': + $ref: '#/components/responses/ServerError' + description: Invalid request + default: + $ref: '#/components/responses/ServerError' + description: Internal server error + summary: List all variables + tags: + - Variables + post: + operationId: PostVariables + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable created + default: + $ref: '#/components/responses/ServerError' + description: Internal server error + summary: Create a variable + tags: + - Variables + /api/v2/variables/{variableID}: + delete: + operationId: DeleteVariablesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + responses: + '204': + description: Variable deleted + default: + $ref: '#/components/responses/ServerError' + description: Internal server error + summary: Delete a variable + tags: + - Variables + get: + operationId: GetVariablesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable found + '404': + $ref: '#/components/responses/ServerError' + description: Variable not found + default: + $ref: '#/components/responses/ServerError' + description: Internal server error + summary: Retrieve a variable + tags: + - Variables + patch: + operationId: PatchVariablesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable updated + default: + $ref: '#/components/responses/ServerError' + description: Internal server error + summary: Update a variable + tags: + - Variables + put: + operationId: PutVariablesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable to replace + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable updated + default: + $ref: '#/components/responses/ServerError' + description: Internal server error + summary: Replace a variable + tags: + - Variables + /api/v2/variables/{variableID}/labels: + get: + operationId: GetVariablesIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a variable + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a variable + tags: + - Variables + post: + operationId: PostVariablesIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true schema: - $ref: '#/components/schemas/Error' - description: Non 2XX error response from server. - securitySchemes: - TokenAuthentication: - type: http - scheme: token - bearerFormat: InfluxDB Token String + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The newly added label + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a variable + tags: + - Variables + /api/v2/variables/{variableID}/labels/{labelID}: + delete: + operationId: DeleteVariablesIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + - description: The label ID to delete. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Variable not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label from a variable + tags: + - Variables + /api/v2/write: + post: description: > - ### Token authentication scheme + Writes data to a bucket. - InfluxDB API tokens ensure secure interaction between users and data. A - token belongs to an organization and identifies InfluxDB permissions - within the organization. + To write data into InfluxDB, you need the following: + + - **organization** – _See [View + organizations](https://docs.influxdata.com/influxdb/v2.0/organizations/view-orgs/#view-your-organization-id) + for instructions on viewing your organization ID._ + + - **bucket** – _See [View + buckets](https://docs.influxdata.com/influxdb/v2.0/organizations/buckets/view-buckets/) + for + instructions on viewing your bucket ID._ + - **API token** – _See [View + tokens](https://docs.influxdata.com/influxdb/v2.0/security/tokens/view-tokens/) + for instructions on viewing your API token._ + - **InfluxDB URL** – _See [InfluxDB + URLs](https://docs.influxdata.com/influxdb/v2.0/reference/urls/)_. + + - data in [line + protocol](https://docs.influxdata.com/influxdb/v2.0/reference/syntax/line-protocol) + format. + + + For more information and examples, see [Write data with the InfluxDB + API](https://docs.influxdata.com/influxdb/v2.0/write-data/developer-tools/api). + operationId: PostWrite + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: >- + When present, the header value tells the database that compression + is applied to the line protocol in the request body. + in: header + name: Content-Encoding + schema: + default: identity + description: >- + The header value specifies that the line protocol in the request + body is encoded with gzip or not encoded with identity. + enum: + - gzip + - identity + type: string + - description: >- + The header value indicates the format of the data in the request + body. + in: header + name: Content-Type + schema: + default: text/plain; charset=utf-8 + description: > + `text/plain` specifies line protocol. `UTF-8` is the default + character set. + enum: + - text/plain + - text/plain; charset=utf-8 + - application/vnd.influx.arrow + type: string + - description: >- + The header value indicates the size of the entity-body, in bytes, + sent to the database. If the length is greater than the database's + `max body` configuration option, the server responds with status + code `413`. + in: header + name: Content-Length + schema: + description: The length in decimal number of octets. + type: integer + - description: The header value specifies the response format. + in: header + name: Accept + schema: + default: application/json + description: The response format for errors. + enum: + - application/json + type: string + - description: >- + The parameter value specifies the destination organization for + writes. The database writes all points in the batch to this + organization. If you provide both `orgID` and `org` parameters, + `org` takes precedence. + in: query + name: org + required: true + schema: + description: Organization name or ID. + type: string + - description: >- + The parameter value specifies the ID of the destination organization + for writes. If both `orgID` and `org` are specified, `org` takes + precedence. + in: query + name: orgID + schema: + type: string + - description: The destination bucket for writes. + in: query + name: bucket + required: true + schema: + description: All points within batch are written to this bucket. + type: string + - description: The precision for the unix timestamps within the body line-protocol. + in: query + name: precision + schema: + $ref: '#/components/schemas/WritePrecision' + requestBody: + content: + text/plain: + schema: + format: byte + type: string + description: Data in line protocol format. + required: true + responses: + '204': + description: >- + InfluxDB validated the request data format and accepted the data for + writing to the bucket. `204` doesn't indicate a successful write + operation since writes are asynchronous. See [how to check for write + errors](https://docs.influxdata.com/influxdb/v2.0/write-data/troubleshoot). + '400': + content: + application/json: + examples: + measurementSchemaFieldTypeConflict: + summary: >- + Example of a field type conflict thrown by an explicit + bucket schema + value: + code: invalid + message: >- + partial write error (2 written): unable to parse + 'air_sensor,service=S1,sensor=L1 + temperature="90.5",humidity=70.0 1632850122': schema: + field type for field "temperature" not permitted by + schema; got String but expected Float + schema: + $ref: '#/components/schemas/LineProtocolError' + description: >- + Bad request. The line protocol data in the request is malformed. The + response body contains the first malformed line in the data. + InfluxDB rejected the batch and did not write any data. + '401': + content: + application/json: + examples: + tokenNotAuthorized: + summary: >- + Token is not authorized to access the organization or + resource + value: + code: unauthorized + message: unauthorized access + schema: + $ref: '#/components/schemas/Error' + description: | + Unauthorized. The error may indicate one of the following: + * The `Authorization: Token` header is missing or malformed. + * The API token value is missing from the header. + * The token does not have sufficient permissions to write to this organization and bucket. + '404': + content: + application/json: + examples: + resource-not-found: + summary: Not found error + value: + code: not found + message: bucket "air_sensor" not found + schema: + $ref: '#/components/schemas/Error' + description: >- + Not found. A requested resource was not found. The response body + contains the requested resource type, e.g. `organization name` or + `bucket`, and name. + '413': + content: + application/json: + schema: + $ref: '#/components/schemas/LineProtocolLengthError' + description: > + All request data was rejected and not written. InfluxDB OSS only + returns this error if the [Go (golang) + `ioutil.ReadAll()`](https://pkg.go.dev/io/ioutil#ReadAll) function + raises an error. + '500': + content: + application/json: + examples: + internalError: + summary: Internal error example + value: + code: internal error + schema: + $ref: '#/components/schemas/Error' + description: Internal server error. + '503': + description: >- + The server is temporarily unavailable to accept writes. The + `Retry-After` header describes when to try the write again. + headers: + Retry-After: + description: >- + A non-negative decimal integer indicating the seconds to delay + after the response is received. + schema: + format: int32 + type: integer + default: + $ref: '#/components/responses/ServerError' + summary: Write data + tags: + - Write +security: + - TokenAuthentication: [] + - BasicAuthentication: [] + - QuerystringAuthentication: [] +servers: + - url: / +tags: + - name: Authentication + description: > + Use one of the following schemes to authenticate to the InfluxDB API: + - [Token authentication](#section/Authentication/TokenAuthentication) - Include your API token in an `Authorization: Token YOUR_API_TOKEN` HTTP - header with each request. + - [Basic authentication](#section/Authentication/BasicAuthentication) + - [Querystring + authentication](#section/Authentication/QuerystringAuthentication) - ### Example + + x-traitTag: true + - name: Authorizations + description: > + Create and manage API tokens. An **authorization** associates a list of + permissions to an **organization** and provides a token for API access. To + assign a token to a specific user, scope the authorization to the user ID. + - Backup + - Buckets + - Cells + - Checks + - Dashboards + - DBRPs + - Delete + - Health + - Labels + - Legacy Authorizations + - NotificationEndpoints + - NotificationRules + - Organizations + - Ping + - name: Query + description: | + Retrieve data, analyze queries, and get query suggestions. + - name: Quick start + x-traitTag: true + description: > + See the [**API Quick + Start**](https://docs.influxdata.com/influxdb/v2.0/api-guide/api_intro/) + to get up and running authenticating with tokens, writing to buckets, and + querying data. - `curl http://localhost:8086/ping - --header "Authorization: Token YOUR_API_TOKEN"` - For more information and examples, see the following: - - [Use tokens in API requests](https://docs.influxdata.com/influxdb/v2.0/api-guide/api_intro/#authentication). - - [Manage API tokens](https://docs.influxdata.com/influxdb/v2.0/security/tokens). - - [`/authorizations`](#tag/Authorizations) endpoint. - BasicAuthentication: - type: http - scheme: basic - description: > - ### Basic authentication scheme + [**InfluxDB API client + libraries**](https://docs.influxdata.com/influxdb/v2.0/api-guide/client-libraries/) + are available for popular languages and ready to import into your + application. + - Ready + - Resources + - name: Response codes + x-traitTag: true + description: > + The InfluxDB API uses standard HTTP status codes for success and failure + responses. + The response body may include additional details. For details about a + specific operation's response, see **Responses** and **Response Samples** + for that operation. - Use HTTP Basic Auth with clients that support the InfluxDB 1.x - convention of username and password (that don't support the - `Authorization: Token` scheme). + API operations may return the following HTTP status codes: - Username and password schemes require the following credentials: - - **username**: 1.x username (this is separate from the UI login username) - - **password**: 1.x password or InfluxDB API token - ### Example + |  Code  | Status | Description | + |:-----------:|:------------------------ |:--------------------- | - `curl --get "http://localhost:8086/query" - --user "YOUR_1.x_USERNAME":"YOUR_TOKEN_OR_PASSWORD"` + | `200` | Success | | - For more information and examples, see how to [authenticate with a - username and password - scheme](https://docs.influxdata.com/influxdb/v2.0/reference/api/influxdb-1x/) - QuerystringAuthentication: - type: apiKey - in: query - name: u=&p= - description: > - ### Querystring authentication scheme + | `204` | No content | For a `POST` request, `204` + indicates that InfluxDB accepted the request and request data is valid. + Asynchronous operations, such as `write`, might not have completed yet. | + | `400` | Bad request | `Authorization` header is + missing or malformed or the API token does not have permission for the + operation. | - Use InfluxDB 1.x API parameters to provide credentials through the query - string. + | `401` | Unauthorized | May indicate one of the + following:
  • `Authorization: Token` header is missing or + malformed
  • API token value is missing from the header
  • API + token does not have permission. For more information about token types and + permissions, see [Manage API + tokens](https://docs.influxdata.com/influxdb/v2.0/security/tokens/)
    • | + | `404` | Not found | Requested resource was not + found. `message` in the response body provides details about the requested + resource. | - Username and password schemes require the following credentials: - - **username**: 1.x username (this is separate from the UI login username) - - **password**: 1.x password or InfluxDB API token + | `413` | Request entity too large | Request payload exceeds the + size limit. | - ### Example + | `422` | Unprocessible entity | Request data is invalid. `code` + and `message` in the response body provide details about the problem. | + | `429` | Too many requests | API token is temporarily over + the request quota. The `Retry-After` header describes when to try the + request again. | - `curl --get "http://localhost:8086/query" - --data-urlencode "u=YOUR_1.x_USERNAME" - --data-urlencode "p=YOUR_TOKEN_OR_PASSWORD"` + | `500` | Internal server error | | - For more information and examples, see how to [authenticate with a - username and password - scheme](https://docs.influxdata.com/influxdb/v2.0/reference/api/influxdb-1x/) -security: - - TokenAuthentication: [] - - BasicAuthentication: [] - - QuerystringAuthentication: [] + | `503` | Service unavailable | Server is temporarily + unavailable to process the request. The `Retry-After` header describes + when to try the request again. | + - Restore + - Routes + - Rules + - Scraper Targets + - Secrets + - Setup + - Signin + - Signout + - Sources + - Tasks + - Telegraf Plugins + - Telegrafs + - Templates + - Users + - Variables + - Views + - name: Write + description: | + Write time series data to buckets. +x-tagGroups: + - name: Overview + tags: + - Quick start + - Authentication + - Response codes + - name: Data I/O endpoints + tags: + - Write + - Query + - name: Resource endpoints + tags: + - Buckets + - Dashboards + - Tasks + - Resources + - name: Security and access endpoints + tags: + - Authorizations + - Organizations + - Users + - name: System information endpoints + tags: + - Health + - Ping + - Ready + - Routes + - name: All endpoints + tags: + - Authorizations + - Backup + - Buckets + - Cells + - Checks + - Dashboards + - DBRPs + - Delete + - Health + - Labels + - Legacy Authorizations + - NotificationEndpoints + - NotificationRules + - Organizations + - Ping + - Query + - Ready + - Resources + - Restore + - Routes + - Rules + - Scraper Targets + - Secrets + - Setup + - Signin + - Signout + - Sources + - Tasks + - Telegraf Plugins + - Telegrafs + - Templates + - Users + - Variables + - Views + - Write diff --git a/api-docs/v2.1/ref.yml b/api-docs/v2.1/ref.yml new file mode 100644 index 0000000000..d900885561 --- /dev/null +++ b/api-docs/v2.1/ref.yml @@ -0,0 +1,13128 @@ +components: + parameters: + After: + description: > + The last resource ID from which to seek from (but not including). This + is to be used instead of `offset`. + in: query + name: after + required: false + schema: + type: string + Descending: + in: query + name: descending + required: false + schema: + default: false + type: boolean + Limit: + in: query + name: limit + required: false + schema: + default: 20 + maximum: 100 + minimum: 1 + type: integer + Offset: + in: query + name: offset + required: false + schema: + minimum: 0 + type: integer + SortBy: + in: query + name: sortBy + required: false + schema: + type: string + TraceSpan: + description: OpenTracing span context + example: + baggage: + key: value + span_id: '1' + trace_id: '1' + in: header + name: Zap-Trace-Span + required: false + schema: + type: string + responses: + ServerError: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Non 2XX error response from server. + schemas: + ASTResponse: + description: Contains the AST for the supplied Flux query + properties: + ast: + $ref: '#/components/schemas/Package' + type: object + AddResourceMemberRequestBody: + properties: + id: + type: string + name: + type: string + required: + - id + type: object + AnalyzeQueryResponse: + properties: + errors: + items: + properties: + character: + type: integer + column: + type: integer + line: + type: integer + message: + type: string + type: object + type: array + type: object + ArrayExpression: + description: Used to create and directly specify the elements of an array object + properties: + elements: + description: Elements of the array + items: + $ref: '#/components/schemas/Expression' + type: array + type: + $ref: '#/components/schemas/NodeType' + type: object + Authorization: + allOf: + - $ref: '#/components/schemas/AuthorizationUpdateRequest' + - properties: + createdAt: + format: date-time + readOnly: true + type: string + id: + readOnly: true + type: string + links: + example: + self: /api/v2/authorizations/1 + user: /api/v2/users/12 + properties: + self: + $ref: '#/components/schemas/Link' + readOnly: true + user: + $ref: '#/components/schemas/Link' + readOnly: true + readOnly: true + type: object + org: + description: Name of the org token is scoped to. + readOnly: true + type: string + orgID: + description: ID of org that authorization is scoped to. + type: string + permissions: + description: >- + List of permissions for an auth. An auth must have at least one + Permission. + items: + $ref: '#/components/schemas/Permission' + minItems: 1 + type: array + token: + description: >- + Passed via the Authorization Header and Token Authentication + type. + readOnly: true + type: string + updatedAt: + format: date-time + readOnly: true + type: string + user: + description: Name of user that created and owns the token. + readOnly: true + type: string + userID: + description: ID of user that created and owns the token. + readOnly: true + type: string + type: object + required: + - orgID + - permissions + AuthorizationPostRequest: + allOf: + - $ref: '#/components/schemas/AuthorizationUpdateRequest' + - properties: + orgID: + description: ID of org that authorization is scoped to. + type: string + permissions: + description: >- + List of permissions for an auth. An auth must have at least one + Permission. + items: + $ref: '#/components/schemas/Permission' + minItems: 1 + type: array + userID: + description: ID of user that authorization is scoped to. + type: string + type: object + required: + - orgID + - permissions + AuthorizationUpdateRequest: + properties: + description: + description: A description of the token. + type: string + status: + default: active + description: >- + If inactive the token is inactive and requests using the token will + be rejected. + enum: + - active + - inactive + type: string + Authorizations: + properties: + authorizations: + items: + $ref: '#/components/schemas/Authorization' + type: array + links: + $ref: '#/components/schemas/Links' + readOnly: true + type: object + Axes: + description: The viewport for a View's visualizations + properties: + x: + $ref: '#/components/schemas/Axis' + 'y': + $ref: '#/components/schemas/Axis' + required: + - x + - 'y' + type: object + Axis: + description: The description of a particular axis for a visualization. + properties: + base: + description: Base represents the radix for formatting axis values. + enum: + - '' + - '2' + - '10' + type: string + bounds: + description: >- + The extents of an axis in the form [lower, upper]. Clients determine + whether bounds are to be inclusive or exclusive of their limits + items: + type: string + maxItems: 2 + minItems: 0 + type: array + label: + description: Label is a description of this Axis + type: string + prefix: + description: Prefix represents a label prefix for formatting axis values. + type: string + scale: + $ref: '#/components/schemas/AxisScale' + suffix: + description: Suffix represents a label suffix for formatting axis values. + type: string + type: object + AxisScale: + description: 'Scale is the axis formatting scale. Supported: "log", "linear"' + enum: + - log + - linear + type: string + BadStatement: + description: >- + A placeholder for statements for which no correct statement nodes can be + created + properties: + text: + description: Raw source text + type: string + type: + $ref: '#/components/schemas/NodeType' + type: object + BandViewProperties: + properties: + axes: + $ref: '#/components/schemas/Axes' + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + generateXAxisTicks: + items: + type: string + type: array + generateYAxisTicks: + items: + type: string + type: array + geom: + $ref: '#/components/schemas/XYGeom' + hoverDimension: + enum: + - auto + - x + - 'y' + - xy + type: string + legendColorizeRows: + type: boolean + legendHide: + type: boolean + legendOpacity: + format: float + type: number + legendOrientationThreshold: + type: integer + lowerColumn: + type: string + mainColumn: + type: string + note: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + staticLegend: + $ref: '#/components/schemas/StaticLegend' + timeFormat: + type: string + type: + enum: + - band + type: string + upperColumn: + type: string + xColumn: + type: string + xTickStart: + format: float + type: number + xTickStep: + format: float + type: number + xTotalTicks: + type: integer + yColumn: + type: string + yTickStart: + format: float + type: number + yTickStep: + format: float + type: number + yTotalTicks: + type: integer + required: + - type + - geom + - queries + - shape + - axes + - colors + - note + - showNoteWhenEmpty + type: object + BinaryExpression: + description: uses binary operators to act on two operands in an expression + properties: + left: + $ref: '#/components/schemas/Expression' + operator: + type: string + right: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + type: object + Block: + description: A set of statements + properties: + body: + description: Block body + items: + $ref: '#/components/schemas/Statement' + type: array + type: + $ref: '#/components/schemas/NodeType' + type: object + BooleanLiteral: + description: Represents boolean values + properties: + type: + $ref: '#/components/schemas/NodeType' + value: + type: boolean + type: object + Bucket: + properties: + createdAt: + format: date-time + readOnly: true + type: string + description: + type: string + id: + readOnly: true + type: string + labels: + $ref: '#/components/schemas/Labels' + links: + example: + labels: /api/v2/buckets/1/labels + members: /api/v2/buckets/1/members + org: /api/v2/orgs/2 + owners: /api/v2/buckets/1/owners + self: /api/v2/buckets/1 + write: /api/v2/write?org=2&bucket=1 + properties: + labels: + $ref: '#/components/schemas/Link' + description: URL to retrieve labels for this bucket + members: + $ref: '#/components/schemas/Link' + description: URL to retrieve members that can read this bucket + org: + $ref: '#/components/schemas/Link' + description: URL to retrieve parent organization for this bucket + owners: + $ref: '#/components/schemas/Link' + description: URL to retrieve owners that can read and write to this bucket. + self: + $ref: '#/components/schemas/Link' + description: URL for this bucket + write: + $ref: '#/components/schemas/Link' + description: URL to write line protocol for this bucket + readOnly: true + type: object + name: + type: string + orgID: + type: string + retentionRules: + $ref: '#/components/schemas/RetentionRules' + rp: + type: string + schemaType: + $ref: '#/components/schemas/SchemaType' + default: implicit + type: + default: user + enum: + - user + - system + readOnly: true + type: string + updatedAt: + format: date-time + readOnly: true + type: string + required: + - name + - retentionRules + BucketMetadataManifest: + properties: + bucketID: + type: string + bucketName: + type: string + defaultRetentionPolicy: + type: string + description: + type: string + organizationID: + type: string + organizationName: + type: string + retentionPolicies: + $ref: '#/components/schemas/RetentionPolicyManifests' + required: + - organizationID + - organizationName + - bucketID + - bucketName + - defaultRetentionPolicy + - retentionPolicies + type: object + BucketMetadataManifests: + items: + $ref: '#/components/schemas/BucketMetadataManifest' + type: array + BucketShardMapping: + properties: + newId: + format: int64 + type: integer + oldId: + format: int64 + type: integer + required: + - oldId + - newId + type: object + BucketShardMappings: + items: + $ref: '#/components/schemas/BucketShardMapping' + type: array + Buckets: + properties: + buckets: + items: + $ref: '#/components/schemas/Bucket' + type: array + links: + $ref: '#/components/schemas/Links' + readOnly: true + type: object + BuilderAggregateFunctionType: + enum: + - filter + - group + type: string + BuilderConfig: + properties: + aggregateWindow: + properties: + fillValues: + type: boolean + period: + type: string + type: object + buckets: + items: + type: string + type: array + functions: + items: + $ref: '#/components/schemas/BuilderFunctionsType' + type: array + tags: + items: + $ref: '#/components/schemas/BuilderTagsType' + type: array + type: object + BuilderFunctionsType: + properties: + name: + type: string + type: object + BuilderTagsType: + properties: + aggregateFunctionType: + $ref: '#/components/schemas/BuilderAggregateFunctionType' + key: + type: string + values: + items: + type: string + type: array + type: object + BuiltinStatement: + description: Declares a builtin identifier and its type + properties: + id: + $ref: '#/components/schemas/Identifier' + type: + $ref: '#/components/schemas/NodeType' + type: object + CallExpression: + description: Represents a function call + properties: + arguments: + description: Function arguments + items: + $ref: '#/components/schemas/Expression' + type: array + callee: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + type: object + Cell: + properties: + h: + format: int32 + type: integer + id: + type: string + links: + properties: + self: + type: string + view: + type: string + type: object + viewID: + description: The reference to a view from the views API. + type: string + w: + format: int32 + type: integer + x: + format: int32 + type: integer + 'y': + format: int32 + type: integer + type: object + CellUpdate: + properties: + h: + format: int32 + type: integer + w: + format: int32 + type: integer + x: + format: int32 + type: integer + 'y': + format: int32 + type: integer + type: object + CellWithViewProperties: + allOf: + - $ref: '#/components/schemas/Cell' + - properties: + name: + type: string + properties: + $ref: '#/components/schemas/ViewProperties' + type: object + type: object + Cells: + items: + $ref: '#/components/schemas/Cell' + type: array + CellsWithViewProperties: + items: + $ref: '#/components/schemas/CellWithViewProperties' + type: array + Check: + allOf: + - $ref: '#/components/schemas/CheckDiscriminator' + CheckBase: + properties: + createdAt: + format: date-time + readOnly: true + type: string + description: + description: An optional description of the check. + type: string + id: + readOnly: true + type: string + labels: + $ref: '#/components/schemas/Labels' + lastRunError: + readOnly: true + type: string + lastRunStatus: + enum: + - failed + - success + - canceled + readOnly: true + type: string + latestCompleted: + description: Timestamp of latest scheduled, completed run, RFC3339. + format: date-time + readOnly: true + type: string + links: + example: + labels: /api/v2/checks/1/labels + members: /api/v2/checks/1/members + owners: /api/v2/checks/1/owners + query: /api/v2/checks/1/query + self: /api/v2/checks/1 + properties: + labels: + $ref: '#/components/schemas/Link' + description: URL to retrieve labels for this check + members: + $ref: '#/components/schemas/Link' + description: URL to retrieve members for this check + owners: + $ref: '#/components/schemas/Link' + description: URL to retrieve owners for this check + query: + $ref: '#/components/schemas/Link' + description: URL to retrieve flux script for this check + self: + $ref: '#/components/schemas/Link' + description: URL for this check + readOnly: true + type: object + name: + type: string + orgID: + description: The ID of the organization that owns this check. + type: string + ownerID: + description: The ID of creator used to create this check. + readOnly: true + type: string + query: + $ref: '#/components/schemas/DashboardQuery' + status: + $ref: '#/components/schemas/TaskStatusType' + taskID: + description: The ID of the task associated with this check. + type: string + updatedAt: + format: date-time + readOnly: true + type: string + required: + - name + - orgID + - query + CheckDiscriminator: + discriminator: + mapping: + custom: '#/components/schemas/CustomCheck' + deadman: '#/components/schemas/DeadmanCheck' + threshold: '#/components/schemas/ThresholdCheck' + propertyName: type + oneOf: + - $ref: '#/components/schemas/DeadmanCheck' + - $ref: '#/components/schemas/ThresholdCheck' + - $ref: '#/components/schemas/CustomCheck' + CheckPatch: + properties: + description: + type: string + name: + type: string + status: + enum: + - active + - inactive + type: string + type: object + CheckStatusLevel: + description: The state to record if check matches a criteria. + enum: + - UNKNOWN + - OK + - INFO + - CRIT + - WARN + type: string + CheckViewProperties: + properties: + check: + $ref: '#/components/schemas/Check' + checkID: + type: string + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + legendColorizeRows: + type: boolean + legendHide: + type: boolean + legendOpacity: + format: float + type: number + legendOrientationThreshold: + type: integer + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + type: + enum: + - check + type: string + required: + - type + - shape + - checkID + - queries + - colors + type: object + Checks: + properties: + checks: + items: + $ref: '#/components/schemas/Check' + type: array + links: + $ref: '#/components/schemas/Links' + ConditionalExpression: + description: >- + Selects one of two expressions, `Alternate` or `Consequent`, depending + on a third boolean expression, `Test` + properties: + alternate: + $ref: '#/components/schemas/Expression' + consequent: + $ref: '#/components/schemas/Expression' + test: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + type: object + ConstantVariableProperties: + properties: + type: + enum: + - constant + type: string + values: + items: + type: string + type: array + CreateCell: + properties: + h: + format: int32 + type: integer + name: + type: string + usingView: + description: Makes a copy of the provided view. + type: string + w: + format: int32 + type: integer + x: + format: int32 + type: integer + 'y': + format: int32 + type: integer + type: object + CreateDashboardRequest: + properties: + description: + description: The user-facing description of the dashboard. + type: string + name: + description: The user-facing name of the dashboard. + type: string + orgID: + description: The ID of the organization that owns the dashboard. + type: string + required: + - orgID + - name + CustomCheck: + allOf: + - $ref: '#/components/schemas/CheckBase' + - properties: + type: + enum: + - custom + type: string + required: + - type + type: object + DBRP: + properties: + bucketID: + description: the bucket ID used as target for the translation. + type: string + database: + description: InfluxDB v1 database + type: string + default: + description: >- + Specify if this mapping represents the default retention policy for + the database specificed. + type: boolean + id: + description: the mapping identifier + readOnly: true + type: string + links: + $ref: '#/components/schemas/Links' + orgID: + description: the organization ID that owns this mapping. + type: string + retention_policy: + description: InfluxDB v1 retention policy + type: string + required: + - id + - orgID + - bucketID + - database + - retention_policy + - default + type: object + DBRPCreate: + properties: + bucketID: + description: the bucket ID used as target for the translation. + type: string + database: + description: InfluxDB v1 database + type: string + default: + description: >- + Specify if this mapping represents the default retention policy for + the database specificed. + type: boolean + org: + description: the organization that owns this mapping. + type: string + orgID: + description: the organization ID that owns this mapping. + type: string + retention_policy: + description: InfluxDB v1 retention policy + type: string + required: + - bucketID + - database + - retention_policy + type: object + DBRPGet: + properties: + content: + $ref: '#/components/schemas/DBRP' + required: true + type: object + DBRPUpdate: + properties: + default: + type: boolean + retention_policy: + description: InfluxDB v1 retention policy + type: string + DBRPs: + properties: + content: + items: + $ref: '#/components/schemas/DBRP' + type: array + Dashboard: + allOf: + - $ref: '#/components/schemas/CreateDashboardRequest' + - properties: + cells: + $ref: '#/components/schemas/Cells' + id: + readOnly: true + type: string + labels: + $ref: '#/components/schemas/Labels' + links: + example: + cells: /api/v2/dashboards/1/cells + labels: /api/v2/dashboards/1/labels + members: /api/v2/dashboards/1/members + org: /api/v2/labels/1 + owners: /api/v2/dashboards/1/owners + self: /api/v2/dashboards/1 + properties: + cells: + $ref: '#/components/schemas/Link' + labels: + $ref: '#/components/schemas/Link' + members: + $ref: '#/components/schemas/Link' + org: + $ref: '#/components/schemas/Link' + owners: + $ref: '#/components/schemas/Link' + self: + $ref: '#/components/schemas/Link' + type: object + meta: + properties: + createdAt: + format: date-time + type: string + updatedAt: + format: date-time + type: string + type: object + type: object + type: object + DashboardColor: + description: Defines an encoding of data value into color space. + properties: + hex: + description: The hex number of the color + maxLength: 7 + minLength: 7 + type: string + id: + description: The unique ID of the view color. + type: string + name: + description: The user-facing name of the hex color. + type: string + type: + description: Type is how the color is used. + enum: + - min + - max + - threshold + - scale + - text + - background + type: string + value: + description: The data value mapped to this color. + format: float + type: number + required: + - id + - type + - hex + - name + - value + type: object + DashboardQuery: + properties: + builderConfig: + $ref: '#/components/schemas/BuilderConfig' + editMode: + $ref: '#/components/schemas/QueryEditMode' + name: + type: string + text: + description: The text of the Flux query. + type: string + type: object + DashboardWithViewProperties: + allOf: + - $ref: '#/components/schemas/CreateDashboardRequest' + - properties: + cells: + $ref: '#/components/schemas/CellsWithViewProperties' + id: + readOnly: true + type: string + labels: + $ref: '#/components/schemas/Labels' + links: + example: + cells: /api/v2/dashboards/1/cells + labels: /api/v2/dashboards/1/labels + members: /api/v2/dashboards/1/members + org: /api/v2/labels/1 + owners: /api/v2/dashboards/1/owners + self: /api/v2/dashboards/1 + properties: + cells: + $ref: '#/components/schemas/Link' + labels: + $ref: '#/components/schemas/Link' + members: + $ref: '#/components/schemas/Link' + org: + $ref: '#/components/schemas/Link' + owners: + $ref: '#/components/schemas/Link' + self: + $ref: '#/components/schemas/Link' + type: object + meta: + properties: + createdAt: + format: date-time + type: string + updatedAt: + format: date-time + type: string + type: object + type: object + type: object + Dashboards: + properties: + dashboards: + items: + $ref: '#/components/schemas/Dashboard' + type: array + links: + $ref: '#/components/schemas/Links' + type: object + DateTimeLiteral: + description: >- + Represents an instant in time with nanosecond precision using the syntax + of golang's RFC3339 Nanosecond variant + properties: + type: + $ref: '#/components/schemas/NodeType' + value: + format: date-time + type: string + type: object + DeadmanCheck: + allOf: + - $ref: '#/components/schemas/CheckBase' + - properties: + every: + description: Check repetition interval. + type: string + level: + $ref: '#/components/schemas/CheckStatusLevel' + offset: + description: Duration to delay after the schedule, before executing check. + type: string + reportZero: + description: If only zero values reported since time, trigger an alert + type: boolean + staleTime: + description: >- + String duration for time that a series is considered stale and + should not trigger deadman. + type: string + statusMessageTemplate: + description: The template used to generate and write a status message. + type: string + tags: + description: List of tags to write to each status. + items: + properties: + key: + type: string + value: + type: string + type: object + type: array + timeSince: + description: String duration before deadman triggers. + type: string + type: + enum: + - deadman + type: string + required: + - type + type: object + DecimalPlaces: + description: >- + Indicates whether decimal places should be enforced, and how many digits + it should show. + properties: + digits: + description: The number of digits after decimal to display + format: int32 + type: integer + isEnforced: + description: Indicates whether decimal point setting should be enforced + type: boolean + type: object + DeletePredicateRequest: + description: The delete predicate request. + properties: + predicate: + description: InfluxQL-like delete statement + example: tag1="value1" and (tag2="value2" and tag3!="value3") + type: string + start: + description: RFC3339Nano + format: date-time + type: string + stop: + description: RFC3339Nano + format: date-time + type: string + required: + - start + - stop + type: object + Dialect: + description: >- + Dialect are options to change the default CSV output format; + https://www.w3.org/TR/2015/REC-tabular-metadata-20151217/#dialect-descriptions + properties: + annotations: + description: https://www.w3.org/TR/2015/REC-tabular-data-model-20151217/#columns + items: + enum: + - group + - datatype + - default + type: string + type: array + uniqueItems: true + commentPrefix: + default: '#' + description: Character prefixed to comment strings + maxLength: 1 + minLength: 0 + type: string + dateTimeFormat: + default: RFC3339 + description: Format of timestamps + enum: + - RFC3339 + - RFC3339Nano + type: string + delimiter: + default: ',' + description: Separator between cells; the default is , + maxLength: 1 + minLength: 1 + type: string + header: + default: true + description: If true, the results will contain a header row + type: boolean + type: object + DictExpression: + description: Used to create and directly specify the elements of a dictionary + properties: + elements: + description: Elements of the dictionary + items: + $ref: '#/components/schemas/DictItem' + type: array + type: + $ref: '#/components/schemas/NodeType' + type: object + DictItem: + description: A key/value pair in a dictionary + properties: + key: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + val: + $ref: '#/components/schemas/Expression' + type: object + Duration: + description: >- + A pair consisting of length of time and the unit of time measured. It is + the atomic unit from which all duration literals are composed. + properties: + magnitude: + type: integer + type: + $ref: '#/components/schemas/NodeType' + unit: + type: string + type: object + DurationLiteral: + description: >- + Represents the elapsed time between two instants as an int64 nanosecond + count with syntax of golang's time.Duration + properties: + type: + $ref: '#/components/schemas/NodeType' + values: + description: Duration values + items: + $ref: '#/components/schemas/Duration' + type: array + type: object + Error: + properties: + code: + description: code is the machine-readable error code. + enum: + - internal error + - not found + - conflict + - invalid + - unprocessable entity + - empty value + - unavailable + - forbidden + - too many requests + - unauthorized + - method not allowed + - request too large + - unsupported media type + readOnly: true + type: string + err: + description: >- + err is a stack of errors that occurred during processing of the + request. Useful for debugging. + readOnly: true + type: string + message: + description: message is a human-readable message. + readOnly: true + type: string + op: + description: >- + op describes the logical code operation during error. Useful for + debugging. + readOnly: true + type: string + required: + - code + - message + Expression: + oneOf: + - $ref: '#/components/schemas/ArrayExpression' + - $ref: '#/components/schemas/DictExpression' + - $ref: '#/components/schemas/FunctionExpression' + - $ref: '#/components/schemas/BinaryExpression' + - $ref: '#/components/schemas/CallExpression' + - $ref: '#/components/schemas/ConditionalExpression' + - $ref: '#/components/schemas/LogicalExpression' + - $ref: '#/components/schemas/MemberExpression' + - $ref: '#/components/schemas/IndexExpression' + - $ref: '#/components/schemas/ObjectExpression' + - $ref: '#/components/schemas/ParenExpression' + - $ref: '#/components/schemas/PipeExpression' + - $ref: '#/components/schemas/UnaryExpression' + - $ref: '#/components/schemas/BooleanLiteral' + - $ref: '#/components/schemas/DateTimeLiteral' + - $ref: '#/components/schemas/DurationLiteral' + - $ref: '#/components/schemas/FloatLiteral' + - $ref: '#/components/schemas/IntegerLiteral' + - $ref: '#/components/schemas/PipeLiteral' + - $ref: '#/components/schemas/RegexpLiteral' + - $ref: '#/components/schemas/StringLiteral' + - $ref: '#/components/schemas/UnsignedIntegerLiteral' + - $ref: '#/components/schemas/Identifier' + ExpressionStatement: + description: >- + May consist of an expression that does not return a value and is + executed solely for its side-effects + properties: + expression: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + type: object + Field: + properties: + alias: + description: >- + Alias overrides the field name in the returned response. Applies + only if type is `func` + type: string + args: + description: Args are the arguments to the function + items: + $ref: '#/components/schemas/Field' + type: array + type: + description: >- + `type` describes the field type. `func` is a function. `field` is a + field reference. + enum: + - func + - field + - integer + - number + - regex + - wildcard + type: string + value: + description: >- + value is the value of the field. Meaning of the value is implied by + the `type` key + type: string + type: object + File: + description: Represents a source from a single file + properties: + body: + description: List of Flux statements + items: + $ref: '#/components/schemas/Statement' + type: array + imports: + description: A list of package imports + items: + $ref: '#/components/schemas/ImportDeclaration' + type: array + name: + description: The name of the file. + type: string + package: + $ref: '#/components/schemas/PackageClause' + type: + $ref: '#/components/schemas/NodeType' + type: object + Flags: + additionalProperties: true + type: object + FloatLiteral: + description: >- + Represents floating point numbers according to the double + representations defined by the IEEE-754-1985 + properties: + type: + $ref: '#/components/schemas/NodeType' + value: + type: number + type: object + FluxResponse: + description: Rendered flux that backs the check or notification. + properties: + flux: + type: string + FluxSuggestion: + properties: + name: + type: string + params: + additionalProperties: + type: string + type: object + type: object + FluxSuggestions: + properties: + funcs: + items: + $ref: '#/components/schemas/FluxSuggestion' + type: array + type: object + FunctionExpression: + description: Function expression + properties: + body: + $ref: '#/components/schemas/Node' + params: + description: Function parameters + items: + $ref: '#/components/schemas/Property' + type: array + type: + $ref: '#/components/schemas/NodeType' + type: object + GaugeViewProperties: + properties: + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + decimalPlaces: + $ref: '#/components/schemas/DecimalPlaces' + note: + type: string + prefix: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + suffix: + type: string + tickPrefix: + type: string + tickSuffix: + type: string + type: + enum: + - gauge + type: string + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - prefix + - tickPrefix + - suffix + - tickSuffix + - decimalPlaces + type: object + GeoCircleViewLayer: + allOf: + - $ref: '#/components/schemas/GeoViewLayerProperties' + - properties: + colorDimension: + $ref: '#/components/schemas/Axis' + colorField: + description: Circle color field + type: string + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + interpolateColors: + description: Interpolate circle color based on displayed value + type: boolean + radius: + description: Maximum radius size in pixels + type: integer + radiusDimension: + $ref: '#/components/schemas/Axis' + radiusField: + description: Radius field + type: string + required: + - radiusField + - radiusDimension + - colorField + - colorDimension + - colors + type: object + GeoHeatMapViewLayer: + allOf: + - $ref: '#/components/schemas/GeoViewLayerProperties' + - properties: + blur: + description: Blur for heatmap points + type: integer + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + intensityDimension: + $ref: '#/components/schemas/Axis' + intensityField: + description: Intensity field + type: string + radius: + description: Radius size in pixels + type: integer + required: + - intensityField + - intensityDimension + - radius + - blur + - colors + type: object + GeoPointMapViewLayer: + allOf: + - $ref: '#/components/schemas/GeoViewLayerProperties' + - properties: + colorDimension: + $ref: '#/components/schemas/Axis' + colorField: + description: Marker color field + type: string + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + isClustered: + description: Cluster close markers together + type: boolean + tooltipColumns: + description: An array for which columns to display in tooltip + items: + type: string + type: array + required: + - colorField + - colorDimension + - colors + type: object + GeoTrackMapViewLayer: + allOf: + - $ref: '#/components/schemas/GeoViewLayerProperties' + - required: + - trackWidth + - speed + - randomColors + - trackPointVisualization + type: object + properties: + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + randomColors: + description: Assign different colors to different tracks + type: boolean + speed: + description: Speed of the track animation + type: integer + trackWidth: + description: Width of the track + type: integer + GeoViewLayer: + oneOf: + - $ref: '#/components/schemas/GeoCircleViewLayer' + - $ref: '#/components/schemas/GeoHeatMapViewLayer' + - $ref: '#/components/schemas/GeoPointMapViewLayer' + - $ref: '#/components/schemas/GeoTrackMapViewLayer' + type: object + GeoViewLayerProperties: + properties: + type: + enum: + - heatmap + - circleMap + - pointMap + - trackMap + type: string + required: + - type + type: object + GeoViewProperties: + properties: + allowPanAndZoom: + default: true + description: If true, map zoom and pan controls are enabled on the dashboard view + type: boolean + center: + description: Coordinates of the center of the map + properties: + lat: + description: Latitude of the center of the map + format: double + type: number + lon: + description: Longitude of the center of the map + format: double + type: number + required: + - lat + - lon + type: object + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + detectCoordinateFields: + default: true + description: >- + If true, search results get automatically regroupped so that lon,lat + and value are treated as columns + type: boolean + latLonColumns: + $ref: '#/components/schemas/LatLonColumns' + layers: + description: List of individual layers shown in the map + items: + $ref: '#/components/schemas/GeoViewLayer' + type: array + mapStyle: + description: Define map type - regular, satellite etc. + type: string + note: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + s2Column: + description: String to define the column + type: string + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + type: + enum: + - geo + type: string + useS2CellID: + description: If true, S2 column is used to calculate lat/lon + type: boolean + zoom: + description: Zoom level used for initial display of the map + format: double + maximum: 28 + minimum: 1 + type: number + required: + - type + - shape + - queries + - note + - showNoteWhenEmpty + - center + - zoom + - allowPanAndZoom + - detectCoordinateFields + - layers + type: object + GreaterThreshold: + allOf: + - $ref: '#/components/schemas/ThresholdBase' + - properties: + type: + enum: + - greater + type: string + value: + format: float + type: number + required: + - type + - value + type: object + HTTPNotificationEndpoint: + allOf: + - $ref: '#/components/schemas/NotificationEndpointBase' + - properties: + authMethod: + enum: + - none + - basic + - bearer + type: string + contentTemplate: + type: string + headers: + additionalProperties: + type: string + description: Customized headers. + type: object + method: + enum: + - POST + - GET + - PUT + type: string + password: + type: string + token: + type: string + url: + type: string + username: + type: string + required: + - url + - authMethod + - method + type: object + type: object + HTTPNotificationRule: + allOf: + - $ref: '#/components/schemas/NotificationRuleBase' + - $ref: '#/components/schemas/HTTPNotificationRuleBase' + HTTPNotificationRuleBase: + properties: + type: + enum: + - http + type: string + url: + type: string + required: + - type + type: object + HealthCheck: + properties: + checks: + items: + $ref: '#/components/schemas/HealthCheck' + type: array + commit: + type: string + message: + type: string + name: + type: string + status: + enum: + - pass + - fail + type: string + version: + type: string + required: + - name + - status + type: object + HeatmapViewProperties: + properties: + binSize: + type: number + colors: + description: Colors define color encoding of data into a visualization + items: + type: string + type: array + generateXAxisTicks: + items: + type: string + type: array + generateYAxisTicks: + items: + type: string + type: array + legendColorizeRows: + type: boolean + legendHide: + type: boolean + legendOpacity: + format: float + type: number + legendOrientationThreshold: + type: integer + note: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + timeFormat: + type: string + type: + enum: + - heatmap + type: string + xAxisLabel: + type: string + xColumn: + type: string + xDomain: + items: + type: number + maxItems: 2 + type: array + xPrefix: + type: string + xSuffix: + type: string + xTickStart: + format: float + type: number + xTickStep: + format: float + type: number + xTotalTicks: + type: integer + yAxisLabel: + type: string + yColumn: + type: string + yDomain: + items: + type: number + maxItems: 2 + type: array + yPrefix: + type: string + ySuffix: + type: string + yTickStart: + format: float + type: number + yTickStep: + format: float + type: number + yTotalTicks: + type: integer + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - xColumn + - yColumn + - xDomain + - yDomain + - xAxisLabel + - yAxisLabel + - xPrefix + - yPrefix + - xSuffix + - ySuffix + - binSize + type: object + HistogramViewProperties: + properties: + binCount: + type: integer + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + fillColumns: + items: + type: string + type: array + legendColorizeRows: + type: boolean + legendHide: + type: boolean + legendOpacity: + format: float + type: number + legendOrientationThreshold: + type: integer + note: + type: string + position: + enum: + - overlaid + - stacked + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + type: + enum: + - histogram + type: string + xAxisLabel: + type: string + xColumn: + type: string + xDomain: + items: + format: float + type: number + type: array + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - xColumn + - fillColumns + - xDomain + - xAxisLabel + - position + - binCount + type: object + Identifier: + description: A valid Flux identifier + properties: + name: + type: string + type: + $ref: '#/components/schemas/NodeType' + type: object + ImportDeclaration: + description: Declares a package import + properties: + as: + $ref: '#/components/schemas/Identifier' + path: + $ref: '#/components/schemas/StringLiteral' + type: + $ref: '#/components/schemas/NodeType' + type: object + IndexExpression: + description: Represents indexing into an array + properties: + array: + $ref: '#/components/schemas/Expression' + index: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + type: object + IntegerLiteral: + description: Represents integer numbers + properties: + type: + $ref: '#/components/schemas/NodeType' + value: + type: string + type: object + IsOnboarding: + properties: + allowed: + description: >- + True means that the influxdb instance has NOT had initial setup; + false means that the database has been setup. + type: boolean + type: object + Label: + properties: + id: + readOnly: true + type: string + name: + type: string + orgID: + readOnly: true + type: string + properties: + additionalProperties: + type: string + description: >- + Key/Value pairs associated with this label. Keys can be removed by + sending an update with an empty value. + example: + color: ffb3b3 + description: this is a description + type: object + type: object + LabelCreateRequest: + properties: + name: + type: string + orgID: + type: string + properties: + additionalProperties: + type: string + description: >- + Key/Value pairs associated with this label. Keys can be removed by + sending an update with an empty value. + example: + color: ffb3b3 + description: this is a description + type: object + required: + - orgID + - name + type: object + LabelMapping: + properties: + labelID: + type: string + type: object + LabelResponse: + properties: + label: + $ref: '#/components/schemas/Label' + links: + $ref: '#/components/schemas/Links' + type: object + LabelUpdate: + properties: + name: + type: string + properties: + additionalProperties: + type: string + description: >- + Key/Value pairs associated with this label. Keys can be removed by + sending an update with an empty value. + example: + color: ffb3b3 + description: this is a description + type: object + type: object + Labels: + items: + $ref: '#/components/schemas/Label' + type: array + LabelsResponse: + properties: + labels: + $ref: '#/components/schemas/Labels' + links: + $ref: '#/components/schemas/Links' + type: object + LanguageRequest: + description: Flux query to be analyzed. + properties: + query: + description: Flux query script to be analyzed + type: string + required: + - query + type: object + LatLonColumn: + description: Object type for key and column definitions + properties: + column: + description: Column to look up Lat/Lon + type: string + key: + description: Key to determine whether the column is tag/field + type: string + required: + - key + - column + type: object + LatLonColumns: + description: Object type to define lat/lon columns + properties: + lat: + $ref: '#/components/schemas/LatLonColumn' + lon: + $ref: '#/components/schemas/LatLonColumn' + required: + - lat + - lon + type: object + LegacyAuthorizationPostRequest: + allOf: + - $ref: '#/components/schemas/AuthorizationUpdateRequest' + - properties: + orgID: + description: ID of org that authorization is scoped to. + type: string + permissions: + description: >- + List of permissions for an auth. An auth must have at least one + Permission. + items: + $ref: '#/components/schemas/Permission' + minItems: 1 + type: array + token: + description: Token (name) of the authorization + type: string + userID: + description: ID of user that authorization is scoped to. + type: string + type: object + required: + - orgID + - permissions + LesserThreshold: + allOf: + - $ref: '#/components/schemas/ThresholdBase' + - properties: + type: + enum: + - lesser + type: string + value: + format: float + type: number + required: + - type + - value + type: object + LinePlusSingleStatProperties: + properties: + axes: + $ref: '#/components/schemas/Axes' + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + decimalPlaces: + $ref: '#/components/schemas/DecimalPlaces' + generateXAxisTicks: + items: + type: string + type: array + generateYAxisTicks: + items: + type: string + type: array + hoverDimension: + enum: + - auto + - x + - 'y' + - xy + type: string + legendColorizeRows: + type: boolean + legendHide: + type: boolean + legendOpacity: + format: float + type: number + legendOrientationThreshold: + type: integer + note: + type: string + position: + enum: + - overlaid + - stacked + type: string + prefix: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shadeBelow: + type: boolean + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + staticLegend: + $ref: '#/components/schemas/StaticLegend' + suffix: + type: string + timeFormat: + type: string + type: + enum: + - line-plus-single-stat + type: string + xColumn: + type: string + xTickStart: + format: float + type: number + xTickStep: + format: float + type: number + xTotalTicks: + type: integer + yColumn: + type: string + yTickStart: + format: float + type: number + yTickStep: + format: float + type: number + yTotalTicks: + type: integer + required: + - type + - queries + - shape + - axes + - colors + - note + - showNoteWhenEmpty + - prefix + - suffix + - decimalPlaces + - position + type: object + LineProtocolError: + properties: + code: + description: Code is the machine-readable error code. + enum: + - internal error + - not found + - conflict + - invalid + - empty value + - unavailable + readOnly: true + type: string + err: + description: >- + Err is a stack of errors that occurred during processing of the + request. Useful for debugging. + readOnly: true + type: string + line: + description: First line within sent body containing malformed data + format: int32 + readOnly: true + type: integer + message: + description: Message is a human-readable message. + readOnly: true + type: string + op: + description: >- + Op describes the logical code operation during error. Useful for + debugging. + readOnly: true + type: string + required: + - code + - message + - op + - err + LineProtocolLengthError: + properties: + code: + description: Code is the machine-readable error code. + enum: + - invalid + readOnly: true + type: string + maxLength: + description: Max length in bytes for a body of line-protocol. + format: int32 + readOnly: true + type: integer + message: + description: Message is a human-readable message. + readOnly: true + type: string + required: + - code + - message + - maxLength + Link: + description: URI of resource. + format: uri + readOnly: true + type: string + Links: + properties: + next: + $ref: '#/components/schemas/Link' + prev: + $ref: '#/components/schemas/Link' + self: + $ref: '#/components/schemas/Link' + required: + - self + type: object + LogEvent: + properties: + message: + description: A description of the event that occurred. + example: Halt and catch fire + readOnly: true + type: string + runID: + description: the ID of the task that logged + readOnly: true + type: string + time: + description: Time event occurred, RFC3339Nano. + format: date-time + readOnly: true + type: string + type: object + LogicalExpression: + description: >- + Represents the rule conditions that collectively evaluate to either true + or false + properties: + left: + $ref: '#/components/schemas/Expression' + operator: + type: string + right: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + type: object + Logs: + properties: + events: + items: + $ref: '#/components/schemas/LogEvent' + readOnly: true + type: array + type: object + MapVariableProperties: + properties: + type: + enum: + - map + type: string + values: + additionalProperties: + type: string + type: object + MarkdownViewProperties: + properties: + note: + type: string + shape: + enum: + - chronograf-v2 + type: string + type: + enum: + - markdown + type: string + required: + - type + - shape + - note + type: object + MemberAssignment: + description: Object property assignment + properties: + init: + $ref: '#/components/schemas/Expression' + member: + $ref: '#/components/schemas/MemberExpression' + type: + $ref: '#/components/schemas/NodeType' + type: object + MemberExpression: + description: Represents accessing a property of an object + properties: + object: + $ref: '#/components/schemas/Expression' + property: + $ref: '#/components/schemas/PropertyKey' + type: + $ref: '#/components/schemas/NodeType' + type: object + MetadataBackup: + properties: + buckets: + $ref: '#/components/schemas/BucketMetadataManifests' + kv: + format: binary + type: string + sql: + format: binary + type: string + required: + - kv + - sql + - buckets + type: object + MosaicViewProperties: + properties: + colors: + description: Colors define color encoding of data into a visualization + items: + type: string + type: array + fillColumns: + items: + type: string + type: array + generateXAxisTicks: + items: + type: string + type: array + hoverDimension: + enum: + - auto + - x + - 'y' + - xy + type: string + legendColorizeRows: + type: boolean + legendHide: + type: boolean + legendOpacity: + format: float + type: number + legendOrientationThreshold: + type: integer + note: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + timeFormat: + type: string + type: + enum: + - mosaic + type: string + xAxisLabel: + type: string + xColumn: + type: string + xDomain: + items: + type: number + maxItems: 2 + type: array + xPrefix: + type: string + xSuffix: + type: string + xTickStart: + format: float + type: number + xTickStep: + format: float + type: number + xTotalTicks: + type: integer + yAxisLabel: + type: string + yDomain: + items: + type: number + maxItems: 2 + type: array + yLabelColumnSeparator: + type: string + yLabelColumns: + items: + type: string + type: array + yPrefix: + type: string + ySeriesColumns: + items: + type: string + type: array + ySuffix: + type: string + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - xColumn + - ySeriesColumns + - fillColumns + - xDomain + - yDomain + - xAxisLabel + - yAxisLabel + - xPrefix + - yPrefix + - xSuffix + - ySuffix + type: object + Node: + oneOf: + - $ref: '#/components/schemas/Expression' + - $ref: '#/components/schemas/Block' + NodeType: + description: Type of AST node + type: string + NotificationEndpoint: + allOf: + - $ref: '#/components/schemas/NotificationEndpointDiscriminator' + NotificationEndpointBase: + properties: + createdAt: + format: date-time + readOnly: true + type: string + description: + description: An optional description of the notification endpoint. + type: string + id: + type: string + labels: + $ref: '#/components/schemas/Labels' + links: + example: + labels: /api/v2/notificationEndpoints/1/labels + members: /api/v2/notificationEndpoints/1/members + owners: /api/v2/notificationEndpoints/1/owners + self: /api/v2/notificationEndpoints/1 + properties: + labels: + $ref: '#/components/schemas/Link' + description: URL to retrieve labels for this endpoint. + members: + $ref: '#/components/schemas/Link' + description: URL to retrieve members for this endpoint. + owners: + $ref: '#/components/schemas/Link' + description: URL to retrieve owners for this endpoint. + self: + $ref: '#/components/schemas/Link' + description: URL for this endpoint. + readOnly: true + type: object + name: + type: string + orgID: + type: string + status: + default: active + description: The status of the endpoint. + enum: + - active + - inactive + type: string + type: + $ref: '#/components/schemas/NotificationEndpointType' + updatedAt: + format: date-time + readOnly: true + type: string + userID: + type: string + required: + - type + - name + type: object + NotificationEndpointDiscriminator: + discriminator: + mapping: + http: '#/components/schemas/HTTPNotificationEndpoint' + pagerduty: '#/components/schemas/PagerDutyNotificationEndpoint' + slack: '#/components/schemas/SlackNotificationEndpoint' + telegram: '#/components/schemas/TelegramNotificationEndpoint' + propertyName: type + oneOf: + - $ref: '#/components/schemas/SlackNotificationEndpoint' + - $ref: '#/components/schemas/PagerDutyNotificationEndpoint' + - $ref: '#/components/schemas/HTTPNotificationEndpoint' + - $ref: '#/components/schemas/TelegramNotificationEndpoint' + NotificationEndpointType: + enum: + - slack + - pagerduty + - http + - telegram + type: string + NotificationEndpointUpdate: + properties: + description: + type: string + name: + type: string + status: + enum: + - active + - inactive + type: string + type: object + NotificationEndpoints: + properties: + links: + $ref: '#/components/schemas/Links' + notificationEndpoints: + items: + $ref: '#/components/schemas/NotificationEndpoint' + type: array + NotificationRule: + allOf: + - $ref: '#/components/schemas/NotificationRuleDiscriminator' + NotificationRuleBase: + properties: + createdAt: + format: date-time + readOnly: true + type: string + description: + description: An optional description of the notification rule. + type: string + endpointID: + type: string + every: + description: The notification repetition interval. + type: string + id: + readOnly: true + type: string + labels: + $ref: '#/components/schemas/Labels' + lastRunError: + readOnly: true + type: string + lastRunStatus: + enum: + - failed + - success + - canceled + readOnly: true + type: string + latestCompleted: + description: Timestamp of latest scheduled, completed run, RFC3339. + format: date-time + readOnly: true + type: string + limit: + description: >- + Don't notify me more than times every seconds. + If set, limitEvery cannot be empty. + type: integer + limitEvery: + description: >- + Don't notify me more than times every seconds. + If set, limit cannot be empty. + type: integer + links: + example: + labels: /api/v2/notificationRules/1/labels + members: /api/v2/notificationRules/1/members + owners: /api/v2/notificationRules/1/owners + query: /api/v2/notificationRules/1/query + self: /api/v2/notificationRules/1 + properties: + labels: + $ref: '#/components/schemas/Link' + description: URL to retrieve labels for this notification rule. + members: + $ref: '#/components/schemas/Link' + description: URL to retrieve members for this notification rule. + owners: + $ref: '#/components/schemas/Link' + description: URL to retrieve owners for this notification rule. + query: + $ref: '#/components/schemas/Link' + description: URL to retrieve flux script for this notification rule. + self: + $ref: '#/components/schemas/Link' + description: URL for this endpoint. + readOnly: true + type: object + name: + description: Human-readable name describing the notification rule. + type: string + offset: + description: Duration to delay after the schedule, before executing check. + type: string + orgID: + description: The ID of the organization that owns this notification rule. + type: string + ownerID: + description: The ID of creator used to create this notification rule. + readOnly: true + type: string + runbookLink: + type: string + sleepUntil: + type: string + status: + $ref: '#/components/schemas/TaskStatusType' + statusRules: + description: List of status rules the notification rule attempts to match. + items: + $ref: '#/components/schemas/StatusRule' + minItems: 1 + type: array + tagRules: + description: List of tag rules the notification rule attempts to match. + items: + $ref: '#/components/schemas/TagRule' + type: array + taskID: + description: The ID of the task associated with this notification rule. + type: string + updatedAt: + format: date-time + readOnly: true + type: string + required: + - orgID + - status + - name + - statusRules + - endpointID + type: object + NotificationRuleDiscriminator: + discriminator: + mapping: + http: '#/components/schemas/HTTPNotificationRule' + pagerduty: '#/components/schemas/PagerDutyNotificationRule' + slack: '#/components/schemas/SlackNotificationRule' + smtp: '#/components/schemas/SMTPNotificationRule' + telegram: '#/components/schemas/TelegramNotificationRule' + propertyName: type + oneOf: + - $ref: '#/components/schemas/SlackNotificationRule' + - $ref: '#/components/schemas/SMTPNotificationRule' + - $ref: '#/components/schemas/PagerDutyNotificationRule' + - $ref: '#/components/schemas/HTTPNotificationRule' + - $ref: '#/components/schemas/TelegramNotificationRule' + NotificationRuleUpdate: + properties: + description: + type: string + name: + type: string + status: + enum: + - active + - inactive + type: string + type: object + NotificationRules: + properties: + links: + $ref: '#/components/schemas/Links' + notificationRules: + items: + $ref: '#/components/schemas/NotificationRule' + type: array + ObjectExpression: + description: Allows the declaration of an anonymous object within a declaration + properties: + properties: + description: Object properties + items: + $ref: '#/components/schemas/Property' + type: array + type: + $ref: '#/components/schemas/NodeType' + type: object + OnboardingRequest: + properties: + bucket: + type: string + org: + type: string + password: + type: string + retentionPeriodHrs: + deprecated: true + description: > + Retention period *in nanoseconds* for the new bucket. This key's + name has been misleading since OSS 2.0 GA, please transition to use + `retentionPeriodSeconds` + type: integer + retentionPeriodSeconds: + format: int64 + type: integer + token: + description: > + Authentication token to set on the initial user. If not specified, + the server will generate a token. + type: string + username: + type: string + required: + - username + - org + - bucket + type: object + OnboardingResponse: + properties: + auth: + $ref: '#/components/schemas/Authorization' + bucket: + $ref: '#/components/schemas/Bucket' + org: + $ref: '#/components/schemas/Organization' + user: + $ref: '#/components/schemas/UserResponse' + type: object + OptionStatement: + description: A single variable declaration + properties: + assignment: + oneOf: + - $ref: '#/components/schemas/VariableAssignment' + - $ref: '#/components/schemas/MemberAssignment' + type: + $ref: '#/components/schemas/NodeType' + type: object + Organization: + properties: + createdAt: + format: date-time + readOnly: true + type: string + description: + type: string + id: + readOnly: true + type: string + links: + example: + buckets: /api/v2/buckets?org=myorg + dashboards: /api/v2/dashboards?org=myorg + labels: /api/v2/orgs/1/labels + members: /api/v2/orgs/1/members + owners: /api/v2/orgs/1/owners + secrets: /api/v2/orgs/1/secrets + self: /api/v2/orgs/1 + tasks: /api/v2/tasks?org=myorg + properties: + buckets: + $ref: '#/components/schemas/Link' + dashboards: + $ref: '#/components/schemas/Link' + labels: + $ref: '#/components/schemas/Link' + members: + $ref: '#/components/schemas/Link' + owners: + $ref: '#/components/schemas/Link' + secrets: + $ref: '#/components/schemas/Link' + self: + $ref: '#/components/schemas/Link' + tasks: + $ref: '#/components/schemas/Link' + readOnly: true + type: object + name: + type: string + status: + default: active + description: If inactive the organization is inactive. + enum: + - active + - inactive + type: string + updatedAt: + format: date-time + readOnly: true + type: string + required: + - name + Organizations: + properties: + links: + $ref: '#/components/schemas/Links' + orgs: + items: + $ref: '#/components/schemas/Organization' + type: array + type: object + Package: + description: Represents a complete package source tree. + properties: + files: + description: Package files + items: + $ref: '#/components/schemas/File' + type: array + package: + description: Package name + type: string + path: + description: Package import path + type: string + type: + $ref: '#/components/schemas/NodeType' + type: object + PackageClause: + description: Defines a package identifier + properties: + name: + $ref: '#/components/schemas/Identifier' + type: + $ref: '#/components/schemas/NodeType' + type: object + PagerDutyNotificationEndpoint: + allOf: + - $ref: '#/components/schemas/NotificationEndpointBase' + - properties: + clientURL: + type: string + routingKey: + type: string + required: + - routingKey + type: object + type: object + PagerDutyNotificationRule: + allOf: + - $ref: '#/components/schemas/NotificationRuleBase' + - $ref: '#/components/schemas/PagerDutyNotificationRuleBase' + PagerDutyNotificationRuleBase: + properties: + messageTemplate: + type: string + type: + enum: + - pagerduty + type: string + required: + - type + - messageTemplate + type: object + ParenExpression: + description: Represents an expression wrapped in parenthesis + properties: + expression: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + type: object + PasswordResetBody: + properties: + password: + type: string + required: + - password + PatchBucketRequest: + description: Updates to an existing bucket resource. + properties: + description: + type: string + name: + type: string + retentionRules: + $ref: '#/components/schemas/PatchRetentionRules' + type: object + PatchOrganizationRequest: + properties: + description: + description: New description to set on the organization + type: string + name: + description: New name to set on the organization + type: string + type: object + PatchRetentionRule: + description: Updates to a rule to expire or retain data. + properties: + everySeconds: + description: >- + Duration in seconds for how long data will be kept in the database. + 0 means infinite. + example: 86400 + format: int64 + minimum: 0 + type: integer + shardGroupDurationSeconds: + description: Shard duration measured in seconds. + format: int64 + type: integer + type: + default: expire + enum: + - expire + type: string + required: + - type + type: object + PatchRetentionRules: + description: Updates to rules to expire or retain data. No rules means no updates. + items: + $ref: '#/components/schemas/PatchRetentionRule' + type: array + Permission: + properties: + action: + enum: + - read + - write + type: string + resource: + $ref: '#/components/schemas/Resource' + required: + - action + - resource + PipeExpression: + description: Call expression with pipe argument + properties: + argument: + $ref: '#/components/schemas/Expression' + call: + $ref: '#/components/schemas/CallExpression' + type: + $ref: '#/components/schemas/NodeType' + type: object + PipeLiteral: + description: >- + Represents a specialized literal value, indicating the left hand value + of a pipe expression + properties: + type: + $ref: '#/components/schemas/NodeType' + type: object + PostBucketRequest: + properties: + description: + type: string + name: + type: string + orgID: + type: string + retentionRules: + $ref: '#/components/schemas/RetentionRules' + rp: + type: string + schemaType: + $ref: '#/components/schemas/SchemaType' + default: implicit + required: + - orgID + - name + - retentionRules + PostCheck: + allOf: + - $ref: '#/components/schemas/CheckDiscriminator' + PostNotificationEndpoint: + allOf: + - $ref: '#/components/schemas/NotificationEndpointDiscriminator' + PostNotificationRule: + allOf: + - $ref: '#/components/schemas/NotificationRuleDiscriminator' + PostOrganizationRequest: + properties: + description: + type: string + name: + type: string + required: + - name + type: object + Property: + description: The value associated with a key + properties: + key: + $ref: '#/components/schemas/PropertyKey' + type: + $ref: '#/components/schemas/NodeType' + value: + $ref: '#/components/schemas/Expression' + type: object + PropertyKey: + oneOf: + - $ref: '#/components/schemas/Identifier' + - $ref: '#/components/schemas/StringLiteral' + Query: + description: Query influx using the Flux language + properties: + dialect: + $ref: '#/components/schemas/Dialect' + extern: + $ref: '#/components/schemas/File' + now: + description: >- + Specifies the time that should be reported as "now" in the query. + Default is the server's now time. + format: date-time + type: string + params: + additionalProperties: true + description: > + Enumeration of key/value pairs that respresent parameters to be + injected into query (can only specify either this field or extern + and not both) + type: object + query: + description: Query script to execute. + type: string + type: + description: The type of query. Must be "flux". + enum: + - flux + type: string + required: + - query + type: object + QueryEditMode: + enum: + - builder + - advanced + type: string + QueryVariableProperties: + properties: + type: + enum: + - query + type: string + values: + properties: + language: + type: string + query: + type: string + type: object + RangeThreshold: + allOf: + - $ref: '#/components/schemas/ThresholdBase' + - properties: + max: + format: float + type: number + min: + format: float + type: number + type: + enum: + - range + type: string + within: + type: boolean + required: + - type + - min + - max + - within + type: object + Ready: + properties: + started: + example: 2019-03-13T10:09:33.891196-04:00 + format: date-time + type: string + status: + enum: + - ready + type: string + up: + example: 14m45.911966424s + type: string + type: object + RegexpLiteral: + description: >- + Expressions begin and end with `/` and are regular expressions with + syntax accepted by RE2 + properties: + type: + $ref: '#/components/schemas/NodeType' + value: + type: string + type: object + RenamableField: + description: Describes a field that can be renamed and made visible or invisible. + properties: + displayName: + description: The name that a field is renamed to by the user. + type: string + internalName: + description: The calculated name of a field. + readOnly: true + type: string + visible: + description: Indicates whether this field should be visible on the table. + type: boolean + type: object + Resource: + properties: + id: + description: >- + If ID is set that is a permission for a specific resource. if it is + not set it is a permission for all resources of that resource type. + type: string + name: + description: Optional name of the resource if the resource has a name field. + type: string + org: + description: Optional name of the organization of the organization with orgID. + type: string + orgID: + description: >- + If orgID is set that is a permission for all resources owned my that + org. if it is not set it is a permission for all resources of that + resource type. + type: string + type: + enum: + - authorizations + - buckets + - dashboards + - orgs + - sources + - tasks + - telegrafs + - users + - variables + - scrapers + - secrets + - labels + - views + - documents + - notificationRules + - notificationEndpoints + - checks + - dbrp + - notebooks + - annotations + - remotes + - replications + type: string + required: + - type + type: object + ResourceMember: + allOf: + - $ref: '#/components/schemas/UserResponse' + - properties: + role: + default: member + enum: + - member + type: string + type: object + ResourceMembers: + properties: + links: + properties: + self: + format: uri + type: string + type: object + users: + items: + $ref: '#/components/schemas/ResourceMember' + type: array + type: object + ResourceOwner: + allOf: + - $ref: '#/components/schemas/UserResponse' + - properties: + role: + default: owner + enum: + - owner + type: string + type: object + ResourceOwners: + properties: + links: + properties: + self: + format: uri + type: string + type: object + users: + items: + $ref: '#/components/schemas/ResourceOwner' + type: array + type: object + RestoredBucketMappings: + properties: + id: + description: New ID of the restored bucket + type: string + name: + type: string + shardMappings: + $ref: '#/components/schemas/BucketShardMappings' + required: + - id + - name + - shardMappings + type: object + RetentionPolicyManifest: + properties: + duration: + format: int64 + type: integer + name: + type: string + replicaN: + type: integer + shardGroupDuration: + format: int64 + type: integer + shardGroups: + $ref: '#/components/schemas/ShardGroupManifests' + subscriptions: + $ref: '#/components/schemas/SubscriptionManifests' + required: + - name + - replicaN + - duration + - shardGroupDuration + - shardGroups + - subscriptions + type: object + RetentionPolicyManifests: + items: + $ref: '#/components/schemas/RetentionPolicyManifest' + type: array + RetentionRule: + properties: + everySeconds: + description: >- + Duration in seconds for how long data will be kept in the database. + 0 means infinite. + example: 86400 + format: int64 + minimum: 0 + type: integer + shardGroupDurationSeconds: + description: Shard duration measured in seconds. + format: int64 + type: integer + type: + default: expire + enum: + - expire + type: string + required: + - type + - everySeconds + type: object + RetentionRules: + description: Rules to expire or retain data. No rules means data never expires. + items: + $ref: '#/components/schemas/RetentionRule' + type: array + ReturnStatement: + description: Defines an expression to return + properties: + argument: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + type: object + Routes: + properties: + authorizations: + format: uri + type: string + buckets: + format: uri + type: string + dashboards: + format: uri + type: string + external: + properties: + statusFeed: + format: uri + type: string + type: object + flags: + format: uri + type: string + me: + format: uri + type: string + orgs: + format: uri + type: string + query: + properties: + analyze: + format: uri + type: string + ast: + format: uri + type: string + self: + format: uri + type: string + suggestions: + format: uri + type: string + type: object + setup: + format: uri + type: string + signin: + format: uri + type: string + signout: + format: uri + type: string + sources: + format: uri + type: string + system: + properties: + debug: + format: uri + type: string + health: + format: uri + type: string + metrics: + format: uri + type: string + type: object + tasks: + format: uri + type: string + telegrafs: + format: uri + type: string + users: + format: uri + type: string + variables: + format: uri + type: string + write: + format: uri + type: string + RuleStatusLevel: + description: The state to record if check matches a criteria. + enum: + - UNKNOWN + - OK + - INFO + - CRIT + - WARN + - ANY + type: string + Run: + properties: + finishedAt: + description: Time run finished executing, RFC3339Nano. + format: date-time + readOnly: true + type: string + id: + readOnly: true + type: string + links: + example: + retry: /api/v2/tasks/1/runs/1/retry + self: /api/v2/tasks/1/runs/1 + task: /api/v2/tasks/1 + properties: + retry: + format: uri + type: string + self: + format: uri + type: string + task: + format: uri + type: string + readOnly: true + type: object + log: + description: An array of logs associated with the run. + items: + $ref: '#/components/schemas/LogEvent' + readOnly: true + type: array + requestedAt: + description: Time run was manually requested, RFC3339Nano. + format: date-time + readOnly: true + type: string + scheduledFor: + description: Time used for run's "now" option, RFC3339. + format: date-time + type: string + startedAt: + description: Time run started executing, RFC3339Nano. + format: date-time + readOnly: true + type: string + status: + enum: + - scheduled + - started + - failed + - success + - canceled + readOnly: true + type: string + taskID: + readOnly: true + type: string + RunManually: + properties: + scheduledFor: + description: >- + Time used for run's "now" option, RFC3339. Default is the server's + now time. + format: date-time + nullable: true + type: string + Runs: + properties: + links: + $ref: '#/components/schemas/Links' + runs: + items: + $ref: '#/components/schemas/Run' + type: array + type: object + SMTPNotificationRule: + allOf: + - $ref: '#/components/schemas/NotificationRuleBase' + - $ref: '#/components/schemas/SMTPNotificationRuleBase' + SMTPNotificationRuleBase: + properties: + bodyTemplate: + type: string + subjectTemplate: + type: string + to: + type: string + type: + enum: + - smtp + type: string + required: + - type + - subjectTemplate + - to + type: object + ScatterViewProperties: + properties: + colors: + description: Colors define color encoding of data into a visualization + items: + type: string + type: array + fillColumns: + items: + type: string + type: array + generateXAxisTicks: + items: + type: string + type: array + generateYAxisTicks: + items: + type: string + type: array + legendColorizeRows: + type: boolean + legendHide: + type: boolean + legendOpacity: + format: float + type: number + legendOrientationThreshold: + type: integer + note: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + symbolColumns: + items: + type: string + type: array + timeFormat: + type: string + type: + enum: + - scatter + type: string + xAxisLabel: + type: string + xColumn: + type: string + xDomain: + items: + type: number + maxItems: 2 + type: array + xPrefix: + type: string + xSuffix: + type: string + xTickStart: + format: float + type: number + xTickStep: + format: float + type: number + xTotalTicks: + type: integer + yAxisLabel: + type: string + yColumn: + type: string + yDomain: + items: + type: number + maxItems: 2 + type: array + yPrefix: + type: string + ySuffix: + type: string + yTickStart: + format: float + type: number + yTickStep: + format: float + type: number + yTotalTicks: + type: integer + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - xColumn + - yColumn + - fillColumns + - symbolColumns + - xDomain + - yDomain + - xAxisLabel + - yAxisLabel + - xPrefix + - yPrefix + - xSuffix + - ySuffix + type: object + SchemaType: + enum: + - implicit + - explicit + type: string + ScraperTargetRequest: + properties: + allowInsecure: + default: false + description: Skip TLS verification on endpoint. + type: boolean + bucketID: + description: The ID of the bucket to write to. + type: string + name: + description: The name of the scraper target. + type: string + orgID: + description: The organization ID. + type: string + type: + description: The type of the metrics to be parsed. + enum: + - prometheus + type: string + url: + description: The URL of the metrics endpoint. + example: http://localhost:9090/metrics + type: string + type: object + ScraperTargetResponse: + allOf: + - $ref: '#/components/schemas/ScraperTargetRequest' + - properties: + bucket: + description: The bucket name. + type: string + id: + readOnly: true + type: string + links: + example: + bucket: /api/v2/buckets/1 + members: /api/v2/scrapers/1/members + organization: /api/v2/orgs/1 + owners: /api/v2/scrapers/1/owners + self: /api/v2/scrapers/1 + properties: + bucket: + $ref: '#/components/schemas/Link' + members: + $ref: '#/components/schemas/Link' + organization: + $ref: '#/components/schemas/Link' + owners: + $ref: '#/components/schemas/Link' + self: + $ref: '#/components/schemas/Link' + readOnly: true + type: object + org: + description: The name of the organization. + type: string + type: object + type: object + ScraperTargetResponses: + properties: + configurations: + items: + $ref: '#/components/schemas/ScraperTargetResponse' + type: array + type: object + SecretKeys: + properties: + secrets: + items: + type: string + type: array + type: object + SecretKeysResponse: + allOf: + - $ref: '#/components/schemas/SecretKeys' + - properties: + links: + properties: + org: + type: string + self: + type: string + readOnly: true + type: object + type: object + Secrets: + additionalProperties: + type: string + example: + apikey: abc123xyz + ShardGroupManifest: + properties: + deletedAt: + format: date-time + type: string + endTime: + format: date-time + type: string + id: + format: int64 + type: integer + shards: + $ref: '#/components/schemas/ShardManifests' + startTime: + format: date-time + type: string + truncatedAt: + format: date-time + type: string + required: + - id + - startTime + - endTime + - shards + type: object + ShardGroupManifests: + items: + $ref: '#/components/schemas/ShardGroupManifest' + type: array + ShardManifest: + properties: + id: + format: int64 + type: integer + shardOwners: + $ref: '#/components/schemas/ShardOwners' + required: + - id + - shardOwners + type: object + ShardManifests: + items: + $ref: '#/components/schemas/ShardManifest' + type: array + ShardOwner: + properties: + nodeID: + description: ID of the node that owns a shard. + format: int64 + type: integer + required: + - nodeID + type: object + ShardOwners: + items: + $ref: '#/components/schemas/ShardOwner' + type: array + SimpleTableViewProperties: + properties: + note: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showAll: + type: boolean + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + type: + enum: + - simple-table + type: string + required: + - type + - showAll + - queries + - shape + - note + - showNoteWhenEmpty + type: object + SingleStatViewProperties: + properties: + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + decimalPlaces: + $ref: '#/components/schemas/DecimalPlaces' + note: + type: string + prefix: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + staticLegend: + $ref: '#/components/schemas/StaticLegend' + suffix: + type: string + tickPrefix: + type: string + tickSuffix: + type: string + type: + enum: + - single-stat + type: string + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - prefix + - tickPrefix + - suffix + - tickSuffix + - decimalPlaces + type: object + SlackNotificationEndpoint: + allOf: + - $ref: '#/components/schemas/NotificationEndpointBase' + - properties: + token: + description: Specifies the API token string. Specify either `URL` or `Token`. + type: string + url: + description: >- + Specifies the URL of the Slack endpoint. Specify either `URL` or + `Token`. + type: string + type: object + type: object + SlackNotificationRule: + allOf: + - $ref: '#/components/schemas/NotificationRuleBase' + - $ref: '#/components/schemas/SlackNotificationRuleBase' + SlackNotificationRuleBase: + properties: + channel: + type: string + messageTemplate: + type: string + type: + enum: + - slack + type: string + required: + - type + - messageTemplate + type: object + Source: + properties: + default: + type: boolean + defaultRP: + type: string + id: + type: string + insecureSkipVerify: + type: boolean + languages: + items: + enum: + - flux + - influxql + type: string + readOnly: true + type: array + links: + properties: + buckets: + type: string + health: + type: string + query: + type: string + self: + type: string + type: object + metaUrl: + format: uri + type: string + name: + type: string + orgID: + type: string + password: + type: string + sharedSecret: + type: string + telegraf: + type: string + token: + type: string + type: + enum: + - v1 + - v2 + - self + type: string + url: + format: uri + type: string + username: + type: string + type: object + Sources: + properties: + links: + properties: + self: + format: uri + type: string + type: object + sources: + items: + $ref: '#/components/schemas/Source' + type: array + type: object + Stack: + properties: + createdAt: + format: date-time + readOnly: true + type: string + events: + items: + properties: + description: + type: string + eventType: + type: string + name: + type: string + resources: + items: + properties: + apiVersion: + type: string + associations: + items: + properties: + kind: + $ref: '#/components/schemas/TemplateKind' + metaName: + type: string + type: object + type: array + kind: + $ref: '#/components/schemas/TemplateKind' + links: + properties: + self: + type: string + type: object + resourceID: + type: string + templateMetaName: + type: string + type: object + type: array + sources: + items: + type: string + type: array + updatedAt: + format: date-time + readOnly: true + type: string + urls: + items: + type: string + type: array + type: object + type: array + id: + type: string + orgID: + type: string + type: object + Statement: + oneOf: + - $ref: '#/components/schemas/BadStatement' + - $ref: '#/components/schemas/VariableAssignment' + - $ref: '#/components/schemas/MemberAssignment' + - $ref: '#/components/schemas/ExpressionStatement' + - $ref: '#/components/schemas/ReturnStatement' + - $ref: '#/components/schemas/OptionStatement' + - $ref: '#/components/schemas/BuiltinStatement' + - $ref: '#/components/schemas/TestStatement' + StaticLegend: + description: StaticLegend represents the options specific to the static legend + properties: + colorizeRows: + type: boolean + heightRatio: + format: float + type: number + opacity: + format: float + type: number + orientationThreshold: + type: integer + show: + type: boolean + valueAxis: + type: string + widthRatio: + format: float + type: number + type: object + StatusRule: + properties: + count: + type: integer + currentLevel: + $ref: '#/components/schemas/RuleStatusLevel' + period: + type: string + previousLevel: + $ref: '#/components/schemas/RuleStatusLevel' + type: object + StringLiteral: + description: Expressions begin and end with double quote marks + properties: + type: + $ref: '#/components/schemas/NodeType' + value: + type: string + type: object + SubscriptionManifest: + properties: + destinations: + items: + type: string + type: array + mode: + type: string + name: + type: string + required: + - name + - mode + - destinations + type: object + SubscriptionManifests: + items: + $ref: '#/components/schemas/SubscriptionManifest' + type: array + TableViewProperties: + properties: + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + decimalPlaces: + $ref: '#/components/schemas/DecimalPlaces' + fieldOptions: + description: >- + fieldOptions represent the fields retrieved by the query with + customization options + items: + $ref: '#/components/schemas/RenamableField' + type: array + note: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + tableOptions: + properties: + fixFirstColumn: + description: >- + fixFirstColumn indicates whether the first column of the table + should be locked + type: boolean + sortBy: + $ref: '#/components/schemas/RenamableField' + verticalTimeAxis: + description: >- + verticalTimeAxis describes the orientation of the table by + indicating whether the time axis will be displayed vertically + type: boolean + wrapping: + description: >- + Wrapping describes the text wrapping style to be used in table + views + enum: + - truncate + - wrap + - single-line + type: string + type: object + timeFormat: + description: >- + timeFormat describes the display format for time values according to + moment.js date formatting + type: string + type: + enum: + - table + type: string + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - tableOptions + - fieldOptions + - timeFormat + - decimalPlaces + type: object + TagRule: + properties: + key: + type: string + operator: + enum: + - equal + - notequal + - equalregex + - notequalregex + type: string + value: + type: string + type: object + Task: + properties: + authorizationID: + description: >- + The ID of the authorization used when this task communicates with + the query engine. + type: string + createdAt: + format: date-time + readOnly: true + type: string + cron: + description: >- + A task repetition schedule in the form '* * * * * *'; parsed from + Flux. + type: string + description: + description: An optional description of the task. + type: string + every: + description: A simple task repetition schedule; parsed from Flux. + type: string + flux: + description: The Flux script to run for this task. + type: string + id: + readOnly: true + type: string + labels: + $ref: '#/components/schemas/Labels' + lastRunError: + readOnly: true + type: string + lastRunStatus: + enum: + - failed + - success + - canceled + readOnly: true + type: string + latestCompleted: + description: Timestamp of latest scheduled, completed run, RFC3339. + format: date-time + readOnly: true + type: string + links: + example: + labels: /api/v2/tasks/1/labels + logs: /api/v2/tasks/1/logs + members: /api/v2/tasks/1/members + owners: /api/v2/tasks/1/owners + runs: /api/v2/tasks/1/runs + self: /api/v2/tasks/1 + properties: + labels: + $ref: '#/components/schemas/Link' + logs: + $ref: '#/components/schemas/Link' + members: + $ref: '#/components/schemas/Link' + owners: + $ref: '#/components/schemas/Link' + runs: + $ref: '#/components/schemas/Link' + self: + $ref: '#/components/schemas/Link' + readOnly: true + type: object + name: + description: The name of the task. + type: string + offset: + description: >- + Duration to delay after the schedule, before executing the task; + parsed from flux, if set to zero it will remove this option and use + 0 as the default. + type: string + org: + description: The name of the organization that owns this Task. + type: string + orgID: + description: The ID of the organization that owns this Task. + type: string + ownerID: + description: The ID of the user who owns this Task. + type: string + status: + $ref: '#/components/schemas/TaskStatusType' + type: + description: >- + The type of task, this can be used for filtering tasks on list + actions. + type: string + updatedAt: + format: date-time + readOnly: true + type: string + required: + - id + - name + - orgID + - flux + type: object + TaskCreateRequest: + properties: + description: + description: An optional description of the task. + type: string + flux: + description: The Flux script to run for this task. + type: string + org: + description: The name of the organization that owns this Task. + type: string + orgID: + description: The ID of the organization that owns this Task. + type: string + status: + $ref: '#/components/schemas/TaskStatusType' + required: + - flux + type: object + TaskStatusType: + enum: + - active + - inactive + type: string + TaskUpdateRequest: + properties: + cron: + description: Override the 'cron' option in the flux script. + type: string + description: + description: An optional description of the task. + type: string + every: + description: Override the 'every' option in the flux script. + type: string + flux: + description: The Flux script to run for this task. + type: string + name: + description: Override the 'name' option in the flux script. + type: string + offset: + description: Override the 'offset' option in the flux script. + type: string + status: + $ref: '#/components/schemas/TaskStatusType' + type: object + Tasks: + properties: + links: + $ref: '#/components/schemas/Links' + readOnly: true + tasks: + items: + $ref: '#/components/schemas/Task' + type: array + type: object + Telegraf: + allOf: + - $ref: '#/components/schemas/TelegrafRequest' + - properties: + id: + readOnly: true + type: string + labels: + $ref: '#/components/schemas/Labels' + readOnly: true + links: + example: + lables: /api/v2/telegrafs/1/labels + members: /api/v2/telegrafs/1/members + owners: /api/v2/telegrafs/1/owners + self: /api/v2/telegrafs/1 + properties: + labels: + $ref: '#/components/schemas/Link' + members: + $ref: '#/components/schemas/Link' + owners: + $ref: '#/components/schemas/Link' + self: + $ref: '#/components/schemas/Link' + readOnly: true + type: object + type: object + type: object + TelegrafPlugin: + properties: + config: + type: string + description: + type: string + name: + type: string + type: + type: string + type: object + TelegrafPlugins: + properties: + os: + type: string + plugins: + items: + $ref: '#/components/schemas/TelegrafPlugin' + type: array + version: + type: string + type: object + TelegrafRequest: + properties: + config: + type: string + description: + type: string + metadata: + properties: + buckets: + items: + type: string + type: array + type: object + name: + type: string + orgID: + type: string + type: object + Telegrafs: + properties: + configurations: + items: + $ref: '#/components/schemas/Telegraf' + type: array + type: object + TelegramNotificationEndpoint: + allOf: + - $ref: '#/components/schemas/NotificationEndpointBase' + - properties: + channel: + description: >- + ID of the telegram channel, a chat_id in + https://core.telegram.org/bots/api#sendmessage . + type: string + token: + description: >- + Specifies the Telegram bot token. See + https://core.telegram.org/bots#creating-a-new-bot . + type: string + required: + - token + - channel + type: object + type: object + TelegramNotificationRule: + allOf: + - $ref: '#/components/schemas/NotificationRuleBase' + - $ref: '#/components/schemas/TelegramNotificationRuleBase' + TelegramNotificationRuleBase: + properties: + disableWebPagePreview: + description: >- + Disables preview of web links in the sent messages when "true". + Defaults to "false" . + type: boolean + messageTemplate: + description: The message template as a flux interpolated string. + type: string + parseMode: + description: >- + Parse mode of the message text per + https://core.telegram.org/bots/api#formatting-options . Defaults to + "MarkdownV2" . + enum: + - MarkdownV2 + - HTML + - Markdown + type: string + type: + description: >- + The discriminator between other types of notification rules is + "telegram". + enum: + - telegram + type: string + required: + - type + - messageTemplate + - channel + type: object + Template: + items: + properties: + apiVersion: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + meta: + properties: + name: + type: string + type: object + spec: + type: object + type: object + type: array + TemplateApply: + properties: + actions: + items: + oneOf: + - properties: + action: + enum: + - skipKind + type: string + properties: + properties: + kind: + $ref: '#/components/schemas/TemplateKind' + required: + - kind + type: object + type: object + - properties: + action: + enum: + - skipResource + type: string + properties: + properties: + kind: + $ref: '#/components/schemas/TemplateKind' + resourceTemplateName: + type: string + required: + - kind + - resourceTemplateName + type: object + type: object + type: array + dryRun: + type: boolean + envRefs: + additionalProperties: + oneOf: + - type: string + - type: integer + - type: number + - type: boolean + type: object + orgID: + type: string + remotes: + items: + properties: + contentType: + type: string + url: + type: string + required: + - url + type: object + type: array + secrets: + additionalProperties: + type: string + type: object + stackID: + type: string + template: + properties: + contentType: + type: string + contents: + $ref: '#/components/schemas/Template' + sources: + items: + type: string + type: array + type: object + templates: + items: + properties: + contentType: + type: string + contents: + $ref: '#/components/schemas/Template' + sources: + items: + type: string + type: array + type: object + type: array + type: object + TemplateChart: + properties: + height: + type: integer + properties: + $ref: '#/components/schemas/ViewProperties' + width: + type: integer + xPos: + type: integer + yPos: + type: integer + type: object + TemplateEnvReferences: + items: + properties: + defaultValue: + description: >- + Default value that will be provided for the reference when no + value is provided + nullable: true + oneOf: + - type: string + - type: integer + - type: number + - type: boolean + envRefKey: + description: >- + Key identified as environment reference and is the key identified + in the template + type: string + resourceField: + description: Field the environment reference corresponds too + type: string + value: + description: Value provided to fulfill reference + nullable: true + oneOf: + - type: string + - type: integer + - type: number + - type: boolean + required: + - resourceField + - envRefKey + type: object + type: array + TemplateExportByID: + properties: + orgIDs: + items: + properties: + orgID: + type: string + resourceFilters: + properties: + byLabel: + items: + type: string + type: array + byResourceKind: + items: + $ref: '#/components/schemas/TemplateKind' + type: array + type: object + type: object + type: array + resources: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + name: + description: >- + if defined with id, name is used for resource exported by id. + if defined independently, resources strictly matching name are + exported + type: string + required: + - id + - kind + type: object + type: array + stackID: + type: string + type: object + TemplateExportByName: + properties: + orgIDs: + items: + properties: + orgID: + type: string + resourceFilters: + properties: + byLabel: + items: + type: string + type: array + byResourceKind: + items: + $ref: '#/components/schemas/TemplateKind' + type: array + type: object + type: object + type: array + resources: + items: + properties: + kind: + $ref: '#/components/schemas/TemplateKind' + name: + type: string + required: + - name + - kind + type: object + type: array + stackID: + type: string + type: object + TemplateKind: + enum: + - Bucket + - Check + - CheckDeadman + - CheckThreshold + - Dashboard + - Label + - NotificationEndpoint + - NotificationEndpointHTTP + - NotificationEndpointPagerDuty + - NotificationEndpointSlack + - NotificationRule + - Task + - Telegraf + - Variable + type: string + TemplateSummary: + properties: + diff: + properties: + buckets: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + properties: + description: + type: string + name: + type: string + retentionRules: + $ref: '#/components/schemas/RetentionRules' + type: object + old: + properties: + description: + type: string + name: + type: string + retentionRules: + $ref: '#/components/schemas/RetentionRules' + type: object + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + checks: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + $ref: '#/components/schemas/CheckDiscriminator' + old: + $ref: '#/components/schemas/CheckDiscriminator' + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + dashboards: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + properties: + charts: + items: + $ref: '#/components/schemas/TemplateChart' + type: array + description: + type: string + name: + type: string + type: object + old: + properties: + charts: + items: + $ref: '#/components/schemas/TemplateChart' + type: array + description: + type: string + name: + type: string + type: object + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + labelMappings: + items: + properties: + labelID: + type: string + labelName: + type: string + labelTemplateMetaName: + type: string + resourceID: + type: string + resourceName: + type: string + resourceTemplateMetaName: + type: string + resourceType: + type: string + status: + type: string + type: object + type: array + labels: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + properties: + color: + type: string + description: + type: string + name: + type: string + type: object + old: + properties: + color: + type: string + description: + type: string + name: + type: string + type: object + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + notificationEndpoints: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + $ref: '#/components/schemas/NotificationEndpointDiscriminator' + old: + $ref: '#/components/schemas/NotificationEndpointDiscriminator' + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + notificationRules: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + properties: + description: + type: string + endpointID: + type: string + endpointName: + type: string + endpointType: + type: string + every: + type: string + messageTemplate: + type: string + name: + type: string + offset: + type: string + status: + type: string + statusRules: + items: + properties: + currentLevel: + type: string + previousLevel: + type: string + type: object + type: array + tagRules: + items: + properties: + key: + type: string + operator: + type: string + value: + type: string + type: object + type: array + type: object + old: + properties: + description: + type: string + endpointID: + type: string + endpointName: + type: string + endpointType: + type: string + every: + type: string + messageTemplate: + type: string + name: + type: string + offset: + type: string + status: + type: string + statusRules: + items: + properties: + currentLevel: + type: string + previousLevel: + type: string + type: object + type: array + tagRules: + items: + properties: + key: + type: string + operator: + type: string + value: + type: string + type: object + type: array + type: object + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + tasks: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + properties: + cron: + type: string + description: + type: string + every: + type: string + name: + type: string + offset: + type: string + query: + type: string + status: + type: string + type: object + old: + properties: + cron: + type: string + description: + type: string + every: + type: string + name: + type: string + offset: + type: string + query: + type: string + status: + type: string + type: object + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + telegrafConfigs: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + $ref: '#/components/schemas/TelegrafRequest' + old: + $ref: '#/components/schemas/TelegrafRequest' + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + variables: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + properties: + args: + $ref: '#/components/schemas/VariableProperties' + description: + type: string + name: + type: string + type: object + old: + properties: + args: + $ref: '#/components/schemas/VariableProperties' + description: + type: string + name: + type: string + type: object + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + type: object + errors: + items: + properties: + fields: + items: + type: string + type: array + indexes: + items: + type: integer + type: array + kind: + $ref: '#/components/schemas/TemplateKind' + reason: + type: string + type: object + type: array + sources: + items: + type: string + type: array + stackID: + type: string + summary: + properties: + buckets: + items: + properties: + description: + type: string + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + name: + type: string + orgID: + type: string + retentionPeriod: + type: integer + templateMetaName: + type: string + type: object + type: array + checks: + items: + allOf: + - $ref: '#/components/schemas/CheckDiscriminator' + - properties: + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + templateMetaName: + type: string + type: object + type: array + dashboards: + items: + properties: + charts: + items: + $ref: '#/components/schemas/TemplateChart' + type: array + description: + type: string + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + name: + type: string + orgID: + type: string + templateMetaName: + type: string + type: object + type: array + labelMappings: + items: + properties: + labelID: + type: string + labelName: + type: string + labelTemplateMetaName: + type: string + resourceID: + type: string + resourceName: + type: string + resourceTemplateMetaName: + type: string + resourceType: + type: string + status: + type: string + type: object + type: array + labels: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + missingEnvRefs: + items: + type: string + type: array + missingSecrets: + items: + type: string + type: array + notificationEndpoints: + items: + allOf: + - $ref: '#/components/schemas/NotificationEndpointDiscriminator' + - properties: + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + templateMetaName: + type: string + type: object + type: array + notificationRules: + items: + properties: + description: + type: string + endpointID: + type: string + endpointTemplateMetaName: + type: string + endpointType: + type: string + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + every: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + messageTemplate: + type: string + name: + type: string + offset: + type: string + status: + type: string + statusRules: + items: + properties: + currentLevel: + type: string + previousLevel: + type: string + type: object + type: array + tagRules: + items: + properties: + key: + type: string + operator: + type: string + value: + type: string + type: object + type: array + templateMetaName: + type: string + type: object + type: array + tasks: + items: + properties: + cron: + type: string + description: + type: string + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + every: + type: string + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + name: + type: string + offset: + type: string + query: + type: string + status: + type: string + templateMetaName: + type: string + type: object + type: array + telegrafConfigs: + items: + allOf: + - $ref: '#/components/schemas/TelegrafRequest' + - properties: + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + templateMetaName: + type: string + type: object + type: array + variables: + items: + properties: + arguments: + $ref: '#/components/schemas/VariableProperties' + description: + type: string + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + name: + type: string + orgID: + type: string + templateMetaName: + type: string + type: object + type: array + type: object + type: object + TemplateSummaryLabel: + properties: + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + name: + type: string + orgID: + type: string + properties: + properties: + color: + type: string + description: + type: string + type: object + templateMetaName: + type: string + type: object + TestStatement: + description: Declares a Flux test case + properties: + assignment: + $ref: '#/components/schemas/VariableAssignment' + type: + $ref: '#/components/schemas/NodeType' + type: object + Threshold: + discriminator: + mapping: + greater: '#/components/schemas/GreaterThreshold' + lesser: '#/components/schemas/LesserThreshold' + range: '#/components/schemas/RangeThreshold' + propertyName: type + oneOf: + - $ref: '#/components/schemas/GreaterThreshold' + - $ref: '#/components/schemas/LesserThreshold' + - $ref: '#/components/schemas/RangeThreshold' + ThresholdBase: + properties: + allValues: + description: If true, only alert if all values meet threshold. + type: boolean + level: + $ref: '#/components/schemas/CheckStatusLevel' + ThresholdCheck: + allOf: + - $ref: '#/components/schemas/CheckBase' + - properties: + every: + description: Check repetition interval. + type: string + offset: + description: Duration to delay after the schedule, before executing check. + type: string + statusMessageTemplate: + description: The template used to generate and write a status message. + type: string + tags: + description: List of tags to write to each status. + items: + properties: + key: + type: string + value: + type: string + type: object + type: array + thresholds: + items: + $ref: '#/components/schemas/Threshold' + type: array + type: + enum: + - threshold + type: string + required: + - type + type: object + Token: + properties: + token: + type: string + type: object + UnaryExpression: + description: Uses operators to act on a single operand in an expression + properties: + argument: + $ref: '#/components/schemas/Expression' + operator: + type: string + type: + $ref: '#/components/schemas/NodeType' + type: object + UnsignedIntegerLiteral: + description: Represents integer numbers + properties: + type: + $ref: '#/components/schemas/NodeType' + value: + type: string + type: object + User: + properties: + id: + readOnly: true + type: string + name: + type: string + oauthID: + type: string + status: + default: active + description: If inactive the user is inactive. + enum: + - active + - inactive + type: string + required: + - name + UserResponse: + properties: + id: + readOnly: true + type: string + links: + example: + self: /api/v2/users/1 + properties: + self: + format: uri + type: string + readOnly: true + type: object + name: + type: string + oauthID: + type: string + status: + default: active + description: If inactive the user is inactive. + enum: + - active + - inactive + type: string + required: + - name + Users: + properties: + links: + properties: + self: + format: uri + type: string + type: object + users: + items: + $ref: '#/components/schemas/UserResponse' + type: array + type: object + Variable: + properties: + arguments: + $ref: '#/components/schemas/VariableProperties' + createdAt: + format: date-time + type: string + description: + type: string + id: + readOnly: true + type: string + labels: + $ref: '#/components/schemas/Labels' + links: + properties: + labels: + format: uri + type: string + org: + format: uri + type: string + self: + format: uri + type: string + readOnly: true + type: object + name: + type: string + orgID: + type: string + selected: + items: + type: string + type: array + updatedAt: + format: date-time + type: string + required: + - name + - orgID + - arguments + type: object + VariableAssignment: + description: Represents the declaration of a variable + properties: + id: + $ref: '#/components/schemas/Identifier' + init: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + type: object + VariableProperties: + oneOf: + - $ref: '#/components/schemas/QueryVariableProperties' + - $ref: '#/components/schemas/ConstantVariableProperties' + - $ref: '#/components/schemas/MapVariableProperties' + type: object + Variables: + example: + variables: + - arguments: + type: constant + values: + - howdy + - hello + - hi + - yo + - oy + id: '1221432' + name: ':ok:' + selected: + - hello + - arguments: + type: map + values: + a: fdjaklfdjkldsfjlkjdsa + b: dfaksjfkljekfajekdljfas + c: fdjksajfdkfeawfeea + id: '1221432' + name: ':ok:' + selected: + - c + - arguments: + language: flux + query: 'from(bucket: "foo") |> showMeasurements()' + type: query + id: '1221432' + name: ':ok:' + selected: + - host + properties: + variables: + items: + $ref: '#/components/schemas/Variable' + type: array + type: object + View: + properties: + id: + readOnly: true + type: string + links: + properties: + self: + type: string + readOnly: true + type: object + name: + type: string + properties: + $ref: '#/components/schemas/ViewProperties' + required: + - name + - properties + ViewProperties: + oneOf: + - $ref: '#/components/schemas/LinePlusSingleStatProperties' + - $ref: '#/components/schemas/XYViewProperties' + - $ref: '#/components/schemas/SingleStatViewProperties' + - $ref: '#/components/schemas/HistogramViewProperties' + - $ref: '#/components/schemas/GaugeViewProperties' + - $ref: '#/components/schemas/TableViewProperties' + - $ref: '#/components/schemas/SimpleTableViewProperties' + - $ref: '#/components/schemas/MarkdownViewProperties' + - $ref: '#/components/schemas/CheckViewProperties' + - $ref: '#/components/schemas/ScatterViewProperties' + - $ref: '#/components/schemas/HeatmapViewProperties' + - $ref: '#/components/schemas/MosaicViewProperties' + - $ref: '#/components/schemas/BandViewProperties' + - $ref: '#/components/schemas/GeoViewProperties' + Views: + properties: + links: + properties: + self: + type: string + type: object + views: + items: + $ref: '#/components/schemas/View' + type: array + type: object + WritePrecision: + enum: + - ms + - s + - us + - ns + type: string + XYGeom: + enum: + - line + - step + - stacked + - bar + - monotoneX + type: string + XYViewProperties: + properties: + axes: + $ref: '#/components/schemas/Axes' + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + generateXAxisTicks: + items: + type: string + type: array + generateYAxisTicks: + items: + type: string + type: array + geom: + $ref: '#/components/schemas/XYGeom' + hoverDimension: + enum: + - auto + - x + - 'y' + - xy + type: string + legendColorizeRows: + type: boolean + legendHide: + type: boolean + legendOpacity: + format: float + type: number + legendOrientationThreshold: + type: integer + note: + type: string + position: + enum: + - overlaid + - stacked + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shadeBelow: + type: boolean + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + staticLegend: + $ref: '#/components/schemas/StaticLegend' + timeFormat: + type: string + type: + enum: + - xy + type: string + xColumn: + type: string + xTickStart: + format: float + type: number + xTickStep: + format: float + type: number + xTotalTicks: + type: integer + yColumn: + type: string + yTickStart: + format: float + type: number + yTickStep: + format: float + type: number + yTotalTicks: + type: integer + required: + - type + - geom + - queries + - shape + - axes + - colors + - note + - showNoteWhenEmpty + - position + type: object + securitySchemes: + BasicAuthentication: + description: > + ### Basic authentication scheme + + + Use HTTP Basic Auth with clients that support the InfluxDB 1.x + convention of username and password (that don't support the + `Authorization: Token` scheme). + + + Username and password schemes require the following credentials: + - **username**: 1.x username (this is separate from the UI login username) + - **password**: 1.x password or InfluxDB API token + + #### API token example + + + `curl --get "http://localhost:8086/query" + --user "1.x_USERNAME":"INFLUX_API_TOKEN"` + + #### 1.x password example + + + `curl --get "http://localhost:8086/query" + --user "1.x_USERNAME":"1.x_PASSWORD"` + + Replace the following: + + - *`1.x_USERNAME`*: your InfluxDB v1.x username + + - *`1.x_PASSWORD`*: your InfluxDB v1.x password + + - *`INFLUX_API_TOKEN`*: your [InfluxDB API + token](https://docs.influxdata.com/influxdb/v2.1/reference/glossary/#token) + + + For more information and examples, see how to [authenticate with a + username and password + scheme](https://docs.influxdata.com/influxdb/v2.1/reference/api/influxdb-1x/) + scheme: basic + type: http + QuerystringAuthentication: + description: > + ### Querystring authentication scheme + + + Use InfluxDB 1.x API parameters to provide credentials through the query + string. + + + Username and password schemes require the following credentials: + - **username**: 1.x username (this is separate from the UI login username) + - **password**: 1.x password or InfluxDB API token + + #### API token example + + + `curl --get "http://localhost:8086/query" + --data-urlencode "u=1.x_USERNAME" + --data-urlencode "p=INFLUX_API_TOKEN"` + + #### 1.x password example + + + `curl --get "http://localhost:8086/query" + --data-urlencode "u=1.x_USERNAME" + --data-urlencode "p=1.x_PASSWORD"` + + Replace the following: + + - *`1.x_USERNAME`*: your InfluxDB v1.x username + + - *`1.x_PASSWORD`*: your InfluxDB v1.x password + + - *`INFLUX_API_TOKEN`*: your [InfluxDB API + token](https://docs.influxdata.com/influxdb/v2.1/reference/glossary/#token) + + + For more information and examples, see how to [authenticate with a + username and password + scheme](https://docs.influxdata.com/influxdb/v2.1/reference/api/influxdb-1x/) + in: query + name: u=&p= + type: apiKey + TokenAuthentication: + bearerFormat: InfluxDB Token String + description: > + ### Token authentication scheme + + + InfluxDB API tokens enable authentication and authorization of API + clients. + + A token belongs to an organization and identifies InfluxDB permissions + within the organization. + + + Include your API token in an `Authorization: Token` HTTP header with + each request. + + + #### Example + + `curl http://localhost:8086/ping + --header "Authorization: Token INFLUX_API_TOKEN"` + + Replace *`INFLUX_API_TOKEN`* with your [InfluxDB API + token](https://docs.influxdata.com/influxdb/v2.1/reference/glossary/#token). + + + For more information and examples, see the following: + - [`/authorizations`](#tag/Authorizations) endpoint. + - [Use tokens in API requests](https://docs.influxdata.com/influxdb/v2.1/api-guide/api_intro/#authentication). + - [Manage API tokens](https://docs.influxdata.com/influxdb/v2.1/security/tokens). + - [Assign a token to a specific user](https://docs.influxdata.com/influxdb/v2.1/security/tokens/create-token). + scheme: token + type: http +info: + title: Influx OSS API Service + description: > + The InfluxDB v2 API provides a programmatic interface for all interactions + with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint. +openapi: 3.0.0 +paths: + /api/v2/: + get: + operationId: GetRoutes + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Routes' + description: All routes + summary: List all top level routes + tags: + - Routes + /api/v2/authorizations: + get: + operationId: GetAuthorizations + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Only show authorizations that belong to a user ID. + in: query + name: userID + schema: + type: string + - description: Only show authorizations that belong to a user name. + in: query + name: user + schema: + type: string + - description: Only show authorizations that belong to an organization ID. + in: query + name: orgID + schema: + type: string + - description: Only show authorizations that belong to a organization name. + in: query + name: org + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorizations' + description: A list of authorizations + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: List all authorizations + tags: + - Authorizations + post: + operationId: PostAuthorizations + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationPostRequest' + description: Authorization to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + description: Authorization created + '400': + $ref: '#/components/responses/ServerError' + description: Invalid request + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Create an authorization + tags: + - Authorizations + /api/v2/authorizations/{authID}: + delete: + operationId: DeleteAuthorizationsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the authorization to delete. + in: path + name: authID + required: true + schema: + type: string + responses: + '204': + description: Authorization deleted + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Delete an authorization + tags: + - Authorizations + get: + operationId: GetAuthorizationsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the authorization to get. + in: path + name: authID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + description: Authorization details + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Retrieve an authorization + tags: + - Authorizations + patch: + operationId: PatchAuthorizationsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the authorization to update. + in: path + name: authID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationUpdateRequest' + description: Authorization to update + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + description: The active or inactive authorization + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Update an authorization to be active or inactive + tags: + - Authorizations + /api/v2/backup/kv: + get: + deprecated: true + operationId: GetBackupKV + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/octet-stream: + schema: + format: binary + type: string + description: Snapshot of KV metadata + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: >- + Download snapshot of metadata stored in the server's embedded KV store. + Should not be used in versions greater than 2.1.x, as it doesn't include + metadata stored in embedded SQL. + tags: + - Backup + /api/v2/backup/metadata: + get: + operationId: GetBackupMetadata + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: >- + The Accept-Encoding request HTTP header advertises which content + encoding, usually a compression algorithm, the client is able to + understand. + in: header + name: Accept-Encoding + schema: + default: identity + description: >- + Specifies that the query response in the body should be encoded + with gzip or not encoded with identity. + enum: + - gzip + - identity + type: string + responses: + '200': + content: + multipart/mixed: + schema: + $ref: '#/components/schemas/MetadataBackup' + description: Snapshot of metadata + headers: + Content-Encoding: + description: >- + The Content-Encoding entity header is used to compress the + media-type. When present, its value indicates which encodings + were applied to the entity-body + schema: + default: identity + description: >- + Specifies that the response in the body is encoded with gzip + or not encoded with identity. + enum: + - gzip + - identity + type: string + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Download snapshot of all metadata in the server + tags: + - Backup + /api/v2/backup/shards/{shardID}: + get: + operationId: GetBackupShardId + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: >- + The Accept-Encoding request HTTP header advertises which content + encoding, usually a compression algorithm, the client is able to + understand. + in: header + name: Accept-Encoding + schema: + default: identity + description: >- + Specifies that the query response in the body should be encoded + with gzip or not encoded with identity. + enum: + - gzip + - identity + type: string + - description: The shard ID. + in: path + name: shardID + required: true + schema: + format: int64 + type: integer + - description: Earliest time to include in the snapshot. RFC3339 format. + in: query + name: since + schema: + format: date-time + type: string + responses: + '200': + content: + application/octet-stream: + schema: + format: binary + type: string + description: TSM snapshot. + headers: + Content-Encoding: + description: >- + The Content-Encoding entity header is used to compress the + media-type. When present, its value indicates which encodings + were applied to the entity-body + schema: + default: identity + description: >- + Specifies that the response in the body is encoded with gzip + or not encoded with identity. + enum: + - gzip + - identity + type: string + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Shard not found. + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Download snapshot of all TSM data in a shard + tags: + - Backup + /api/v2/buckets: + get: + operationId: GetBuckets + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/After' + - description: The name of the organization. + in: query + name: org + schema: + type: string + - description: The organization ID. + in: query + name: orgID + schema: + type: string + - description: Only returns buckets with a specific name. + in: query + name: name + schema: + type: string + - description: Only returns buckets with a specific ID. + in: query + name: id + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Buckets' + description: A list of buckets + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all buckets + tags: + - Buckets + post: + operationId: PostBuckets + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PostBucketRequest' + description: Bucket to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Bucket' + description: Bucket created + '422': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Request body failed validation + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a bucket + tags: + - Buckets + /api/v2/buckets/{bucketID}: + delete: + operationId: DeleteBucketsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the bucket to delete. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Bucket not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a bucket + tags: + - Buckets + get: + operationId: GetBucketsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Bucket' + description: Bucket details + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a bucket + tags: + - Buckets + patch: + operationId: PatchBucketsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PatchBucketRequest' + description: Bucket update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Bucket' + description: An updated bucket + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a bucket + tags: + - Buckets + /api/v2/buckets/{bucketID}/labels: + get: + operationId: GetBucketsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a bucket + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a bucket + tags: + - Buckets + post: + operationId: PostBucketsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The newly added label + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a bucket + tags: + - Buckets + /api/v2/buckets/{bucketID}/labels/{labelID}: + delete: + operationId: DeleteBucketsIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + - description: The ID of the label to delete. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Bucket not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label from a bucket + tags: + - Buckets + /api/v2/buckets/{bucketID}/members: + get: + operationId: GetBucketsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMembers' + description: A list of bucket members + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all users with member privileges for a bucket + tags: + - Buckets + post: + operationId: PostBucketsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as member + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMember' + description: Member added to bucket + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a member to a bucket + tags: + - Buckets + /api/v2/buckets/{bucketID}/members/{userID}: + delete: + operationId: DeleteBucketsIDMembersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the member to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '204': + description: Member removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove a member from a bucket + tags: + - Buckets + /api/v2/buckets/{bucketID}/owners: + get: + operationId: GetBucketsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwners' + description: A list of bucket owners + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all owners of a bucket + tags: + - Buckets + post: + operationId: PostBucketsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as owner + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwner' + description: Bucket owner added + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add an owner to a bucket + tags: + - Buckets + /api/v2/buckets/{bucketID}/owners/{userID}: + delete: + operationId: DeleteBucketsIDOwnersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the owner to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '204': + description: Owner removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove an owner from a bucket + tags: + - Buckets + /api/v2/checks: + get: + operationId: GetChecks + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - description: Only show checks that belong to a specific organization ID. + in: query + name: orgID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Checks' + description: A list of checks + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all checks + tags: + - Checks + post: + operationId: CreateCheck + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PostCheck' + description: Check to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Check' + description: Check created + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add new check + tags: + - Checks + /api/v2/checks/{checkID}: + delete: + operationId: DeleteChecksID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The check ID. + in: path + name: checkID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The check was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a check + tags: + - Checks + get: + operationId: GetChecksID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The check ID. + in: path + name: checkID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Check' + description: The check requested + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a check + tags: + - Checks + patch: + operationId: PatchChecksID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The check ID. + in: path + name: checkID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CheckPatch' + description: Check update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Check' + description: An updated check + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The check was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a check + tags: + - Checks + put: + operationId: PutChecksID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The check ID. + in: path + name: checkID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Check' + description: Check update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Check' + description: An updated check + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The check was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a check + tags: + - Checks + /api/v2/checks/{checkID}/labels: + get: + operationId: GetChecksIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The check ID. + in: path + name: checkID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a check + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a check + tags: + - Checks + post: + operationId: PostChecksIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The check ID. + in: path + name: checkID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The label was added to the check + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a check + tags: + - Checks + /api/v2/checks/{checkID}/labels/{labelID}: + delete: + operationId: DeleteChecksIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The check ID. + in: path + name: checkID + required: true + schema: + type: string + - description: The ID of the label to delete. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Check or label not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete label from a check + tags: + - Checks + /api/v2/checks/{checkID}/query: + get: + operationId: GetChecksIDQuery + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The check ID. + in: path + name: checkID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/FluxResponse' + description: The check query requested + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Invalid request + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Check not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a check query + tags: + - Checks + /api/v2/dashboards: + get: + operationId: GetDashboards + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/Descending' + - description: >- + A user identifier. Returns only dashboards where this user has the + `owner` role. + in: query + name: owner + schema: + type: string + - description: The column to sort by. + in: query + name: sortBy + schema: + enum: + - ID + - CreatedAt + - UpdatedAt + type: string + - description: >- + A list of dashboard identifiers. Returns only the listed dashboards. + If both `id` and `owner` are specified, only `id` is used. + in: query + name: id + schema: + items: + type: string + type: array + - description: The identifier of the organization. + in: query + name: orgID + schema: + type: string + - description: The name of the organization. + in: query + name: org + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Dashboards' + description: All dashboards + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all dashboards + tags: + - Dashboards + post: + operationId: PostDashboards + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateDashboardRequest' + description: Dashboard to create + required: true + responses: + '201': + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/Dashboard' + - $ref: '#/components/schemas/DashboardWithViewProperties' + description: Added dashboard + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a dashboard + tags: + - Dashboards + /api/v2/dashboards/{dashboardID}: + delete: + operationId: DeleteDashboardsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the dashboard to update. + in: path + name: dashboardID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a dashboard + tags: + - Dashboards + get: + operationId: GetDashboardsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the dashboard to update. + in: path + name: dashboardID + required: true + schema: + type: string + - description: >- + Includes the cell view properties in the response if set to + `properties` + in: query + name: include + required: false + schema: + enum: + - properties + type: string + responses: + '200': + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/Dashboard' + - $ref: '#/components/schemas/DashboardWithViewProperties' + description: Retrieve a single dashboard + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a Dashboard + tags: + - Dashboards + patch: + operationId: PatchDashboardsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the dashboard to update. + in: path + name: dashboardID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + properties: + cells: + $ref: '#/components/schemas/CellWithViewProperties' + description: >- + optional, when provided will replace all existing cells with + the cells provided + description: + description: optional, when provided will replace the description + type: string + name: + description: optional, when provided will replace the name + type: string + title: PatchDashboardRequest + type: object + description: Patching of a dashboard + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Dashboard' + description: Updated dashboard + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a dashboard + tags: + - Dashboards + /api/v2/dashboards/{dashboardID}/cells: + post: + operationId: PostDashboardsIDCells + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the dashboard to update. + in: path + name: dashboardID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateCell' + description: Cell that will be added + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Cell' + description: Cell successfully added + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a dashboard cell + tags: + - Cells + - Dashboards + put: + description: >- + Replaces all cells in a dashboard. This is used primarily to update the + positional information of all cells. + operationId: PutDashboardsIDCells + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the dashboard to update. + in: path + name: dashboardID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Cells' + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Dashboard' + description: Replaced dashboard cells + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Replace cells in a dashboard + tags: + - Cells + - Dashboards + /api/v2/dashboards/{dashboardID}/cells/{cellID}: + delete: + operationId: DeleteDashboardsIDCellsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the dashboard to delete. + in: path + name: dashboardID + required: true + schema: + type: string + - description: The ID of the cell to delete. + in: path + name: cellID + required: true + schema: + type: string + responses: + '204': + description: Cell successfully deleted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Cell or dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a dashboard cell + tags: + - Cells + - Dashboards + patch: + description: >- + Updates the non positional information related to a cell. Updates to a + single cell's positional data could cause grid conflicts. + operationId: PatchDashboardsIDCellsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the dashboard to update. + in: path + name: dashboardID + required: true + schema: + type: string + - description: The ID of the cell to update. + in: path + name: cellID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CellUpdate' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Cell' + description: Updated dashboard cell + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Cell or dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update the non-positional information related to a cell + tags: + - Cells + - Dashboards + /api/v2/dashboards/{dashboardID}/cells/{cellID}/view: + get: + operationId: GetDashboardsIDCellsIDView + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + - description: The cell ID. + in: path + name: cellID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/View' + description: A dashboard cells view + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Cell or dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve the view for a cell + tags: + - Cells + - Dashboards + - Views + patch: + operationId: PatchDashboardsIDCellsIDView + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the dashboard to update. + in: path + name: dashboardID + required: true + schema: + type: string + - description: The ID of the cell to update. + in: path + name: cellID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/View' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/View' + description: Updated cell view + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Cell or dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update the view for a cell + tags: + - Cells + - Dashboards + - Views + /api/v2/dashboards/{dashboardID}/labels: + get: + operationId: GetDashboardsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a dashboard + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a dashboard + tags: + - Dashboards + post: + operationId: PostDashboardsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The label added to the dashboard + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a dashboard + tags: + - Dashboards + /api/v2/dashboards/{dashboardID}/labels/{labelID}: + delete: + operationId: DeleteDashboardsIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + - description: The ID of the label to delete. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Dashboard not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label from a dashboard + tags: + - Dashboards + /api/v2/dashboards/{dashboardID}/members: + get: + operationId: GetDashboardsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMembers' + description: A list of users who have member privileges for a dashboard + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all dashboard members + tags: + - Dashboards + post: + operationId: PostDashboardsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as member + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMember' + description: Added to dashboard members + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a member to a dashboard + tags: + - Dashboards + /api/v2/dashboards/{dashboardID}/members/{userID}: + delete: + operationId: DeleteDashboardsIDMembersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the member to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + responses: + '204': + description: Member removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove a member from a dashboard + tags: + - Dashboards + /api/v2/dashboards/{dashboardID}/owners: + get: + operationId: GetDashboardsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwners' + description: A list of users who have owner privileges for a dashboard + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all dashboard owners + tags: + - Dashboards + post: + operationId: PostDashboardsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as owner + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwner' + description: Added to dashboard owners + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add an owner to a dashboard + tags: + - Dashboards + /api/v2/dashboards/{dashboardID}/owners/{userID}: + delete: + operationId: DeleteDashboardsIDOwnersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the owner to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The dashboard ID. + in: path + name: dashboardID + required: true + schema: + type: string + responses: + '204': + description: Owner removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove an owner from a dashboard + tags: + - Dashboards + /api/v2/dbrps: + get: + operationId: GetDBRPs + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Specifies the organization ID to filter on + in: query + name: orgID + schema: + type: string + - description: Specifies the organization name to filter on + in: query + name: org + schema: + type: string + - description: Specifies the mapping ID to filter on + in: query + name: id + schema: + type: string + - description: Specifies the bucket ID to filter on + in: query + name: bucketID + schema: + type: string + - description: Specifies filtering on default + in: query + name: default + schema: + type: boolean + - description: Specifies the database to filter on + in: query + name: db + schema: + type: string + - description: Specifies the retention policy to filter on + in: query + name: rp + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/DBRPs' + description: Success. Returns a list of database retention policy mappings. + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Bad request. The request has one or more invalid parameters. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List database retention policy mappings + tags: + - DBRPs + post: + operationId: PostDBRP + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DBRPCreate' + description: The database retention policy mapping to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/DBRP' + description: Created. Returns the created database retention policy mapping. + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Bad request. The mapping in the request has one or more invalid IDs. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a database retention policy mapping + tags: + - DBRPs + /api/v2/dbrps/{dbrpID}: + delete: + operationId: DeleteDBRPID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Specifies the organization ID of the mapping + in: query + name: orgID + schema: + type: string + - description: Specifies the organization name of the mapping + in: query + name: org + schema: + type: string + - description: The database retention policy mapping + in: path + name: dbrpID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: if any of the IDs passed is invalid + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a database retention policy + tags: + - DBRPs + get: + operationId: GetDBRPsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Specifies the organization ID of the mapping + in: query + name: orgID + schema: + type: string + - description: Specifies the organization name of the mapping + in: query + name: org + schema: + type: string + - description: The database retention policy mapping ID + in: path + name: dbrpID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/DBRPGet' + description: The database retention policy requested + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: if any of the IDs passed is invalid + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a database retention policy mapping + tags: + - DBRPs + patch: + operationId: PatchDBRPID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Specifies the organization ID of the mapping + in: query + name: orgID + schema: + type: string + - description: Specifies the organization name of the mapping + in: query + name: org + schema: + type: string + - description: The database retention policy mapping. + in: path + name: dbrpID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DBRPUpdate' + description: Database retention policy update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/DBRPGet' + description: An updated mapping + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: if any of the IDs passed is invalid + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The mapping was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a database retention policy mapping + tags: + - DBRPs + /api/v2/delete: + post: + operationId: PostDelete + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Specifies the organization to delete data from. + in: query + name: org + schema: + description: Only points from this organization are deleted. + type: string + - description: Specifies the bucket to delete data from. + in: query + name: bucket + schema: + description: Only points from this bucket are deleted. + type: string + - description: Specifies the organization ID of the resource. + in: query + name: orgID + schema: + type: string + - description: Specifies the bucket ID to delete data from. + in: query + name: bucketID + schema: + description: Only points from this bucket ID are deleted. + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DeletePredicateRequest' + description: Deletes data from an InfluxDB bucket. + required: true + responses: + '204': + description: delete has been accepted + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Invalid request. + '403': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: no token was sent or does not have sufficient permissions. + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: the bucket or organization is not found. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: internal server error + summary: Delete data + tags: + - Delete + /api/v2/flags: + get: + operationId: GetFlags + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Flags' + description: Feature flags for the currently authenticated user + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Return the feature flags for the currently authenticated user + tags: + - Users + /health: + get: + operationId: GetHealth + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/HealthCheck' + description: The instance is healthy + '503': + content: + application/json: + schema: + $ref: '#/components/schemas/HealthCheck' + description: The instance is unhealthy + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + servers: + - url: '' + summary: Get the health of an instance + tags: + - Health + /api/v2/labels: + get: + operationId: GetLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: query + name: orgID + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of labels + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels + tags: + - Labels + post: + operationId: PostLabels + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelCreateRequest' + description: Label to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: Added label + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a label + tags: + - Labels + /api/v2/labels/{labelID}: + delete: + operationId: DeleteLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the label to delete. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Label not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label + tags: + - Labels + get: + operationId: GetLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the label to update. + in: path + name: labelID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: A label + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a label + tags: + - Labels + patch: + operationId: PatchLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the label to update. + in: path + name: labelID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelUpdate' + description: Label update + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: Updated label + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Label not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a label + tags: + - Labels + /legacy/authorizations: + get: + operationId: GetLegacyAuthorizations + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Only show legacy authorizations that belong to a user ID. + in: query + name: userID + schema: + type: string + - description: Only show legacy authorizations that belong to a user name. + in: query + name: user + schema: + type: string + - description: Only show legacy authorizations that belong to an organization ID. + in: query + name: orgID + schema: + type: string + - description: Only show legacy authorizations that belong to a organization name. + in: query + name: org + schema: + type: string + - description: Only show legacy authorizations with a specified token (auth name). + in: query + name: token + schema: + type: string + - description: Only show legacy authorizations with a specified auth ID. + in: query + name: authID + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorizations' + description: A list of legacy authorizations + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: List all legacy authorizations + tags: + - Legacy Authorizations + post: + operationId: PostLegacyAuthorizations + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LegacyAuthorizationPostRequest' + description: Legacy authorization to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + description: Legacy authorization created + '400': + $ref: '#/components/responses/ServerError' + description: Invalid request + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Create a legacy authorization + tags: + - Legacy Authorizations + servers: + - url: /private + /legacy/authorizations/{authID}: + delete: + operationId: DeleteLegacyAuthorizationsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the legacy authorization to delete. + in: path + name: authID + required: true + schema: + type: string + responses: + '204': + description: Legacy authorization deleted + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Delete a legacy authorization + tags: + - Legacy Authorizations + get: + operationId: GetLegacyAuthorizationsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the legacy authorization to get. + in: path + name: authID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + description: Legacy authorization details + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Retrieve a legacy authorization + tags: + - Legacy Authorizations + patch: + operationId: PatchLegacyAuthorizationsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the legacy authorization to update. + in: path + name: authID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationUpdateRequest' + description: Legacy authorization to update + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + description: The active or inactive legacy authorization + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Update a legacy authorization to be active or inactive + tags: + - Legacy Authorizations + servers: + - url: /private + /legacy/authorizations/{authID}/password: + post: + operationId: PostLegacyAuthorizationsIDPassword + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the legacy authorization to update. + in: path + name: authID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PasswordResetBody' + description: New password + required: true + responses: + '204': + description: Legacy authorization password set + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Set a legacy authorization password + tags: + - Legacy Authorizations + servers: + - url: /private + /api/v2/maps/mapToken: + get: + operationId: getMapboxToken + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Token' + description: A temp token for Mapbox + '401': + $ref: '#/components/responses/ServerError' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/ServerError' + /api/v2/me: + get: + operationId: GetMe + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + description: The currently authenticated user. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve the currently authenticated user + tags: + - Users + /api/v2/me/password: + put: + operationId: PutMePassword + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PasswordResetBody' + description: New password + required: true + responses: + '204': + description: Password successfully updated + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unsuccessful authentication + security: + - BasicAuthentication: [] + summary: Update a password + tags: + - Users + /api/v2/notificationEndpoints: + get: + operationId: GetNotificationEndpoints + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - description: >- + Only show notification endpoints that belong to specific + organization ID. + in: query + name: orgID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationEndpoints' + description: A list of notification endpoints + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all notification endpoints + tags: + - NotificationEndpoints + post: + operationId: CreateNotificationEndpoint + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PostNotificationEndpoint' + description: Notification endpoint to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationEndpoint' + description: Notification endpoint created + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a notification endpoint + tags: + - NotificationEndpoints + /api/v2/notificationEndpoints/{endpointID}: + delete: + operationId: DeleteNotificationEndpointsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification endpoint ID. + in: path + name: endpointID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The endpoint was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a notification endpoint + tags: + - NotificationEndpoints + get: + operationId: GetNotificationEndpointsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification endpoint ID. + in: path + name: endpointID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationEndpoint' + description: The notification endpoint requested + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a notification endpoint + tags: + - NotificationEndpoints + patch: + operationId: PatchNotificationEndpointsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification endpoint ID. + in: path + name: endpointID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationEndpointUpdate' + description: Check update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationEndpoint' + description: An updated notification endpoint + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The notification endpoint was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a notification endpoint + tags: + - NotificationEndpoints + put: + operationId: PutNotificationEndpointsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification endpoint ID. + in: path + name: endpointID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationEndpoint' + description: A new notification endpoint to replace the existing endpoint with + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationEndpoint' + description: An updated notification endpoint + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The notification endpoint was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a notification endpoint + tags: + - NotificationEndpoints + /api/v2/notificationEndpoints/{endpointID}/labels: + get: + operationId: GetNotificationEndpointsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification endpoint ID. + in: path + name: endpointID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a notification endpoint + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a notification endpoint + tags: + - NotificationEndpoints + post: + operationId: PostNotificationEndpointIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification endpoint ID. + in: path + name: endpointID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The label was added to the notification endpoint + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a notification endpoint + tags: + - NotificationEndpoints + /api/v2/notificationEndpoints/{endpointID}/labels/{labelID}: + delete: + operationId: DeleteNotificationEndpointsIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification endpoint ID. + in: path + name: endpointID + required: true + schema: + type: string + - description: The ID of the label to delete. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Endpoint or label not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label from a notification endpoint + tags: + - NotificationEndpoints + /api/v2/notificationRules: + get: + operationId: GetNotificationRules + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - description: >- + Only show notification rules that belong to a specific organization + ID. + in: query + name: orgID + required: true + schema: + type: string + - description: Only show notifications that belong to the specific check ID. + in: query + name: checkID + schema: + type: string + - description: >- + Only return notification rules that "would match" statuses which + contain the tag key value pairs provided. + in: query + name: tag + schema: + example: env:prod + pattern: ^[a-zA-Z0-9_]+:[a-zA-Z0-9_]+$ + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationRules' + description: A list of notification rules + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all notification rules + tags: + - NotificationRules + post: + operationId: CreateNotificationRule + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PostNotificationRule' + description: Notification rule to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationRule' + description: Notification rule created + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a notification rule + tags: + - NotificationRules + /api/v2/notificationRules/{ruleID}: + delete: + operationId: DeleteNotificationRulesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification rule ID. + in: path + name: ruleID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The check was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a notification rule + tags: + - NotificationRules + get: + operationId: GetNotificationRulesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification rule ID. + in: path + name: ruleID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationRule' + description: The notification rule requested + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a notification rule + tags: + - NotificationRules + patch: + operationId: PatchNotificationRulesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification rule ID. + in: path + name: ruleID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationRuleUpdate' + description: Notification rule update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationRule' + description: An updated notification rule + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The notification rule was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a notification rule + tags: + - NotificationRules + put: + operationId: PutNotificationRulesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification rule ID. + in: path + name: ruleID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationRule' + description: Notification rule update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationRule' + description: An updated notification rule + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: The notification rule was not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a notification rule + tags: + - NotificationRules + /api/v2/notificationRules/{ruleID}/labels: + get: + operationId: GetNotificationRulesIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification rule ID. + in: path + name: ruleID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a notification rule + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a notification rule + tags: + - NotificationRules + post: + operationId: PostNotificationRuleIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification rule ID. + in: path + name: ruleID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The label was added to the notification rule + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a notification rule + tags: + - NotificationRules + /api/v2/notificationRules/{ruleID}/labels/{labelID}: + delete: + operationId: DeleteNotificationRulesIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification rule ID. + in: path + name: ruleID + required: true + schema: + type: string + - description: The ID of the label to delete. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Rule or label not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete label from a notification rule + tags: + - NotificationRules + /api/v2/notificationRules/{ruleID}/query: + get: + operationId: GetNotificationRulesIDQuery + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The notification rule ID. + in: path + name: ruleID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/FluxResponse' + description: The notification rule query requested + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Invalid request + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Notification rule not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a notification rule query + tags: + - Rules + /api/v2/orgs: + get: + operationId: GetOrgs + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/Descending' + - description: Filter organizations to a specific organization name. + in: query + name: org + schema: + type: string + - description: Filter organizations to a specific organization ID. + in: query + name: orgID + schema: + type: string + - description: Filter organizations to a specific user ID. + in: query + name: userID + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Organizations' + description: A list of organizations + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all organizations + tags: + - Organizations + post: + operationId: PostOrgs + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PostOrganizationRequest' + description: Organization to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Organization' + description: Organization created + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create an organization + tags: + - Organizations + /api/v2/orgs/{orgID}: + delete: + operationId: DeleteOrgsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the organization to delete. + in: path + name: orgID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Organization not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete an organization + tags: + - Organizations + get: + operationId: GetOrgsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the organization to get. + in: path + name: orgID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Organization' + description: Organization details + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve an organization + tags: + - Organizations + patch: + operationId: PatchOrgsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the organization to get. + in: path + name: orgID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PatchOrganizationRequest' + description: Organization update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Organization' + description: Organization updated + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update an organization + tags: + - Organizations + /api/v2/orgs/{orgID}/members: + get: + operationId: GetOrgsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMembers' + description: A list of organization members + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Organization not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all members of an organization + tags: + - Organizations + post: + operationId: PostOrgsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as member + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMember' + description: Added to organization created + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a member to an organization + tags: + - Organizations + /api/v2/orgs/{orgID}/members/{userID}: + delete: + operationId: DeleteOrgsIDMembersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the member to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + responses: + '204': + description: Member removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove a member from an organization + tags: + - Organizations + /api/v2/orgs/{orgID}/owners: + get: + operationId: GetOrgsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwners' + description: A list of organization owners + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Organization not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all owners of an organization + tags: + - Organizations + post: + operationId: PostOrgsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as owner + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwner' + description: Organization owner added + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add an owner to an organization + tags: + - Organizations + /api/v2/orgs/{orgID}/owners/{userID}: + delete: + operationId: DeleteOrgsIDOwnersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the owner to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + responses: + '204': + description: Owner removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove an owner from an organization + tags: + - Organizations + /api/v2/orgs/{orgID}/secrets: + get: + operationId: GetOrgsIDSecrets + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SecretKeysResponse' + description: A list of all secret keys + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all secret keys for an organization + tags: + - Secrets + patch: + operationId: PatchOrgsIDSecrets + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Secrets' + description: Secret key value pairs to update/add + required: true + responses: + '204': + description: Keys successfully patched + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update secrets in an organization + tags: + - Secrets + /api/v2/orgs/{orgID}/secrets/{secretID}: + delete: + operationId: DeleteOrgsIDSecretsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + - description: The secret ID. + in: path + name: secretID + required: true + schema: + type: string + responses: + '204': + description: Keys successfully deleted + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Delete a secret from an organization + tags: + - Secrets + /api/v2/orgs/{orgID}/secrets/delete: + post: + deprecated: true + operationId: PostOrgsIDSecrets + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SecretKeys' + description: Secret key to delete + required: true + responses: + '204': + description: Keys successfully patched + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete secrets from an organization + tags: + - Secrets + /ping: + get: + operationId: GetPing + responses: + '204': + description: OK + headers: + X-Influxdb-Build: + description: The type of InfluxDB build. + schema: + type: string + X-Influxdb-Version: + description: The version of InfluxDB. + schema: + type: integer + servers: + - url: '' + summary: Checks the status of InfluxDB instance and version of InfluxDB. + tags: + - Ping + head: + operationId: HeadPing + responses: + '204': + description: OK + headers: + X-Influxdb-Build: + description: The type of InfluxDB build. + schema: + type: string + X-Influxdb-Version: + description: The version of InfluxDB. + schema: + type: integer + servers: + - url: '' + summary: Checks the status of InfluxDB instance and version of InfluxDB. + tags: + - Ping + /api/v2/query: + post: + description: > + Retrieves data from InfluxDB buckets. + + + To query data, you need the following: + + - **organization** – _See [View + organizations](https://docs.influxdata.com/influxdb/v2.1/organizations/view-orgs/#view-your-organization-id) + for instructions on viewing your organization ID._ + + - **API token** – _See [View + tokens](https://docs.influxdata.com/influxdb/v2.1/security/tokens/view-tokens/) + for instructions on viewing your API token._ + - **InfluxDB URL** – _See [InfluxDB + URLs](https://docs.influxdata.com/influxdb/v2.1/reference/urls/)_. + + - **Flux query** – _See [Flux](https://docs.influxdata.com/flux/v0.x/)._ + + + For more information and examples, see [Query with the InfluxDB + API](https://docs.influxdata.com/influxdb/v2.1/query-data/execute-queries/influx-api/). + operationId: PostQuery + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: >- + The Accept-Encoding request HTTP header advertises which content + encoding, usually a compression algorithm, the client is able to + understand. + in: header + name: Accept-Encoding + schema: + default: identity + description: >- + Specifies that the query response in the body should be encoded + with gzip or not encoded with identity. + enum: + - gzip + - identity + type: string + - in: header + name: Content-Type + schema: + enum: + - application/json + - application/vnd.flux + type: string + - description: >- + Specifies the name of the organization executing the query. Takes + either the ID or Name. If both `orgID` and `org` are specified, + `org` takes precedence. + in: query + name: org + schema: + type: string + - description: >- + Specifies the ID of the organization executing the query. If both + `orgID` and `org` are specified, `org` takes precedence. + in: query + name: orgID + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + application/vnd.flux: + example: | + from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "example-measurement") + schema: + type: string + description: Flux query or specification to execute + responses: + '200': + content: + application/vnd.influx.arrow: + schema: + format: binary + type: string + text/csv: + schema: + example: > + result,table,_start,_stop,_time,region,host,_value + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 + type: string + description: Success. Returns query results. + headers: + Content-Encoding: + description: >- + The Content-Encoding entity header is used to compress the + media-type. When present, its value indicates which encodings + were applied to the entity-body + schema: + default: identity + description: >- + Specifies that the response in the body is encoded with gzip + or not encoded with identity. + enum: + - gzip + - identity + type: string + Trace-Id: + description: >- + The Trace-Id header reports the request's trace ID, if one was + generated. + schema: + description: Specifies the request's trace ID. + type: string + '429': + description: >- + Token is temporarily over quota. The Retry-After header describes + when to try the read again. + headers: + Retry-After: + description: >- + A non-negative decimal integer indicating the seconds to delay + after the response is received. + schema: + format: int32 + type: integer + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Error processing query + summary: Query data + tags: + - Query + /api/v2/query/analyze: + post: + operationId: PostQueryAnalyze + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: header + name: Content-Type + schema: + enum: + - application/json + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + description: Flux query to analyze + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/AnalyzeQueryResponse' + description: Query analyze results. Errors will be empty if the query is valid. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Internal server error + headers: + X-Influx-Error: + description: Error string describing the problem + schema: + type: string + X-Influx-Reference: + description: Reference code unique to the error type + schema: + type: integer + summary: Analyze a Flux query + tags: + - Query + /api/v2/query/ast: + post: + description: Analyzes flux query and generates a query specification. + operationId: PostQueryAst + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: header + name: Content-Type + schema: + enum: + - application/json + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LanguageRequest' + description: Analyzed Flux query to generate abstract syntax tree. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ASTResponse' + description: Abstract syntax tree of the flux query. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Any response other than 200 is an internal server error + summary: Generate an Abstract Syntax Tree (AST) from a query + tags: + - Query + /api/v2/query/suggestions: + get: + operationId: GetQuerySuggestions + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/FluxSuggestions' + description: Suggestions for next functions in call chain + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Any response other than 200 is an internal server error + summary: Retrieve query suggestions + tags: + - Query + /api/v2/query/suggestions/{name}: + get: + operationId: GetQuerySuggestionsName + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The name of the branching suggestion. + in: path + name: name + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/FluxSuggestion' + description: Suggestions for next functions in call chain + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Any response other than 200 is an internal server error + summary: Retrieve query suggestions for a branching suggestion + tags: + - Query + /ready: + get: + operationId: GetReady + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Ready' + description: The instance is ready + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + servers: + - url: '' + summary: Get the readiness of an instance at startup + tags: + - Ready + /api/v2/resources: + get: + operationId: GetResources + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/json: + schema: + items: + type: string + type: array + description: All resources targets + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Internal server error + summary: List all known resources + tags: + - Resources + /api/v2/restore/bucket/{bucketID}: + post: + deprecated: true + operationId: PostRestoreBucketID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + - in: header + name: Content-Type + schema: + default: application/octet-stream + enum: + - application/octet-stream + type: string + requestBody: + content: + text/plain: + schema: + format: byte + type: string + description: Database info serialized as protobuf. + required: true + responses: + '200': + content: + application/json: + schema: + format: byte + type: string + description: ID mappings for shards in bucket. + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Overwrite storage metadata for a bucket with shard info from a backup. + tags: + - Restore + /api/v2/restore/bucketMetadata: + post: + operationId: PostRestoreBucketMetadata + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/BucketMetadataManifest' + description: Metadata manifest for a bucket. + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/RestoredBucketMappings' + description: ID mappings for shards in new bucket. + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Create a new bucket pre-seeded with shard info from a backup. + tags: + - Restore + /api/v2/restore/kv: + post: + operationId: PostRestoreKV + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: >- + When present, its value indicates to the database that compression + is applied to the line-protocol body. + in: header + name: Content-Encoding + schema: + default: identity + description: >- + Specifies that the line protocol in the body is encoded with gzip + or not encoded with identity. + enum: + - gzip + - identity + type: string + - in: header + name: Content-Type + schema: + default: application/octet-stream + enum: + - application/octet-stream + type: string + requestBody: + content: + text/plain: + schema: + format: binary + type: string + description: Full KV snapshot. + required: true + responses: + '200': + content: + application/json: + schema: + properties: + token: + description: >- + token is the root token for the instance after restore + (this is overwritten during the restore) + type: string + type: object + description: KV store successfully overwritten. + '204': + description: KV store successfully overwritten. + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Overwrite the embedded KV store on the server with a backed-up snapshot. + tags: + - Restore + /api/v2/restore/shards/{shardID}: + post: + operationId: PostRestoreShardId + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: >- + When present, its value indicates to the database that compression + is applied to the line-protocol body. + in: header + name: Content-Encoding + schema: + default: identity + description: >- + Specifies that the line protocol in the body is encoded with gzip + or not encoded with identity. + enum: + - gzip + - identity + type: string + - in: header + name: Content-Type + schema: + default: application/octet-stream + enum: + - application/octet-stream + type: string + - description: The shard ID. + in: path + name: shardID + required: true + schema: + type: string + requestBody: + content: + text/plain: + schema: + format: binary + type: string + description: TSM snapshot. + required: true + responses: + '204': + description: TSM snapshot successfully restored. + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Restore a TSM snapshot into a shard. + tags: + - Restore + /api/v2/restore/sql: + post: + operationId: PostRestoreSQL + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: >- + When present, its value indicates to the database that compression + is applied to the line-protocol body. + in: header + name: Content-Encoding + schema: + default: identity + description: >- + Specifies that the line protocol in the body is encoded with gzip + or not encoded with identity. + enum: + - gzip + - identity + type: string + - in: header + name: Content-Type + schema: + default: application/octet-stream + enum: + - application/octet-stream + type: string + requestBody: + content: + text/plain: + schema: + format: binary + type: string + description: Full SQL snapshot. + required: true + responses: + '204': + description: SQL store successfully overwritten. + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: >- + Overwrite the embedded SQL store on the server with a backed-up + snapshot. + tags: + - Restore + /api/v2/scrapers: + get: + operationId: GetScrapers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Specifies the name of the scraper target. + in: query + name: name + schema: + type: string + - description: >- + List of scraper target IDs to return. If both `id` and `owner` are + specified, only `id` is used. + in: query + name: id + schema: + items: + type: string + type: array + - description: Specifies the organization ID of the scraper target. + in: query + name: orgID + schema: + type: string + - description: Specifies the organization name of the scraper target. + in: query + name: org + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ScraperTargetResponses' + description: All scraper targets + summary: List all scraper targets + tags: + - Scraper Targets + post: + operationId: PostScrapers + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScraperTargetRequest' + description: Scraper target to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ScraperTargetResponse' + description: Scraper target created + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Internal server error + summary: Create a scraper target + tags: + - Scraper Targets + /api/v2/scrapers/{scraperTargetID}: + delete: + operationId: DeleteScrapersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The identifier of the scraper target. + in: path + name: scraperTargetID + required: true + schema: + type: string + responses: + '204': + description: Scraper target deleted + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Internal server error + summary: Delete a scraper target + tags: + - Scraper Targets + get: + operationId: GetScrapersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The identifier of the scraper target. + in: path + name: scraperTargetID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ScraperTargetResponse' + description: The scraper target + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Internal server error + summary: Retrieve a scraper target + tags: + - Scraper Targets + patch: + operationId: PatchScrapersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The identifier of the scraper target. + in: path + name: scraperTargetID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScraperTargetRequest' + description: Scraper target update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ScraperTargetResponse' + description: Scraper target updated + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Internal server error + summary: Update a scraper target + tags: + - Scraper Targets + /api/v2/scrapers/{scraperTargetID}/labels: + get: + operationId: GetScrapersIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of labels for a scraper target. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a scraper target + tags: + - Scraper Targets + post: + operationId: PostScrapersIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The newly added label + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a scraper target + tags: + - Scraper Targets + /api/v2/scrapers/{scraperTargetID}/labels/{labelID}: + delete: + operationId: DeleteScrapersIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + - description: The label ID. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Scraper target not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label from a scraper target + tags: + - Scraper Targets + /api/v2/scrapers/{scraperTargetID}/members: + get: + operationId: GetScrapersIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMembers' + description: A list of scraper target members + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all users with member privileges for a scraper target + tags: + - Scraper Targets + post: + operationId: PostScrapersIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as member + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMember' + description: Member added to scraper targets + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a member to a scraper target + tags: + - Scraper Targets + /api/v2/scrapers/{scraperTargetID}/members/{userID}: + delete: + operationId: DeleteScrapersIDMembersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of member to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + responses: + '204': + description: Member removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove a member from a scraper target + tags: + - Scraper Targets + /api/v2/scrapers/{scraperTargetID}/owners: + get: + operationId: GetScrapersIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwners' + description: A list of scraper target owners + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all owners of a scraper target + tags: + - Scraper Targets + post: + operationId: PostScrapersIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as owner + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwner' + description: Scraper target owner added + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add an owner to a scraper target + tags: + - Scraper Targets + /api/v2/scrapers/{scraperTargetID}/owners/{userID}: + delete: + operationId: DeleteScrapersIDOwnersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of owner to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The scraper target ID. + in: path + name: scraperTargetID + required: true + schema: + type: string + responses: + '204': + description: Owner removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove an owner from a scraper target + tags: + - Scraper Targets + /api/v2/setup: + get: + description: >- + Returns `true` if no default user, organization, or bucket has been + created. + operationId: GetSetup + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/IsOnboarding' + description: allowed true or false + summary: Check if database has default user, org, bucket + tags: + - Setup + post: + description: Post an onboarding request to set up initial user, org and bucket. + operationId: PostSetup + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/OnboardingRequest' + description: Source to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/OnboardingResponse' + description: Created default user, bucket, org + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Set up initial user, org and bucket + tags: + - Setup + /api/v2/signin: + post: + description: >- + Authenticates ***Basic Auth*** credentials for a user. If successful, + creates a new UI session for the user. + operationId: PostSignin + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '204': + description: Success. User authenticated. + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unauthorized access. + '403': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: User account is disabled. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unsuccessful authentication. + security: + - BasicAuthentication: [] + summary: Create a user session. + tags: + - Signin + /api/v2/signout: + post: + description: Expires the current UI session for the user. + operationId: PostSignout + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '204': + description: Session successfully expired + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unauthorized access + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unsuccessful session expiry + summary: Expire the current UI session + tags: + - Signout + /api/v2/sources: + get: + operationId: GetSources + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The name of the organization. + in: query + name: org + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Sources' + description: A list of sources + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all sources + tags: + - Sources + post: + operationId: PostSources + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Source' + description: Source to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Source' + description: Created Source + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a source + tags: + - Sources + /api/v2/sources/{sourceID}: + delete: + operationId: DeleteSourcesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The source ID. + in: path + name: sourceID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: View not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a source + tags: + - Sources + get: + operationId: GetSourcesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The source ID. + in: path + name: sourceID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Source' + description: A source + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Source not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a source + tags: + - Sources + patch: + operationId: PatchSourcesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The source ID. + in: path + name: sourceID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Source' + description: Source update + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Source' + description: Created Source + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Source not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a Source + tags: + - Sources + /api/v2/sources/{sourceID}/buckets: + get: + operationId: GetSourcesIDBuckets + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The source ID. + in: path + name: sourceID + required: true + schema: + type: string + - description: The name of the organization. + in: query + name: org + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Buckets' + description: A source + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Source not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Get buckets in a source + tags: + - Sources + - Buckets + /api/v2/sources/{sourceID}/health: + get: + operationId: GetSourcesIDHealth + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The source ID. + in: path + name: sourceID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/HealthCheck' + description: The source is healthy + '503': + content: + application/json: + schema: + $ref: '#/components/schemas/HealthCheck' + description: The source is not healthy + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Get the health of a source + tags: + - Sources + /api/v2/stacks: + get: + operationId: ListStacks + parameters: + - description: The organization ID of the stacks + in: query + name: orgID + required: true + schema: + type: string + - description: A collection of names to filter the list by. + in: query + name: name + schema: + type: string + - description: A collection of stackIDs to filter the list by. + in: query + name: stackID + schema: + type: string + responses: + '200': + content: + application/json: + schema: + properties: + stacks: + items: + $ref: '#/components/schemas/Stack' + type: array + type: object + description: Success. Returns the list of stacks. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List installed templates + tags: + - Templates + post: + operationId: CreateStack + requestBody: + content: + application/json: + schema: + properties: + description: + type: string + name: + type: string + orgID: + type: string + urls: + items: + type: string + type: array + title: PostStackRequest + type: object + description: The stack to create. + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Stack' + description: Success. Returns the newly created stack. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a new stack + tags: + - Templates + /api/v2/stacks/{stack_id}: + delete: + operationId: DeleteStack + parameters: + - description: The identifier of the stack. + in: path + name: stack_id + required: true + schema: + type: string + - description: The identifier of the organization. + in: query + name: orgID + required: true + schema: + type: string + responses: + '204': + description: The stack and its associated resources were deleted. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a stack and associated resources + tags: + - Templates + get: + operationId: ReadStack + parameters: + - description: The identifier of the stack. + in: path + name: stack_id + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Stack' + description: Returns the stack. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a stack + tags: + - Templates + patch: + operationId: UpdateStack + parameters: + - description: The identifier of the stack. + in: path + name: stack_id + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + properties: + additionalResources: + items: + properties: + kind: + type: string + resourceID: + type: string + templateMetaName: + type: string + required: + - kind + - resourceID + type: object + type: array + description: + nullable: true + type: string + name: + nullable: true + type: string + templateURLs: + items: + type: string + nullable: true + type: array + title: PatchStackRequest + type: object + description: The stack to update. + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Stack' + description: Returns the updated stack. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a stack + tags: + - Templates + /api/v2/stacks/{stack_id}/uninstall: + post: + operationId: UninstallStack + parameters: + - description: The identifier of the stack. + in: path + name: stack_id + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Stack' + description: Returns the uninstalled stack. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Uninstall a stack + tags: + - Templates + /api/v2/tasks: + get: + operationId: GetTasks + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: Returns task with a specific name. + in: query + name: name + schema: + type: string + - description: Return tasks after a specified ID. + in: query + name: after + schema: + type: string + - description: Filter tasks to a specific user ID. + in: query + name: user + schema: + type: string + - description: Filter tasks to a specific organization name. + in: query + name: org + schema: + type: string + - description: Filter tasks to a specific organization ID. + in: query + name: orgID + schema: + type: string + - description: Filter tasks by a status--"inactive" or "active". + in: query + name: status + schema: + enum: + - active + - inactive + type: string + - description: The number of tasks to return + in: query + name: limit + schema: + default: 100 + maximum: 500 + minimum: 1 + type: integer + - description: Type of task, unset by default. + in: query + name: type + required: false + schema: + default: '' + enum: + - basic + - system + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Tasks' + description: A list of tasks + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all tasks + tags: + - Tasks + post: + operationId: PostTasks + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TaskCreateRequest' + description: Task to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + description: Task created + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a new task + tags: + - Tasks + /api/v2/tasks/{taskID}: + delete: + description: Deletes a task and all associated records + operationId: DeleteTasksID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the task to delete. + in: path + name: taskID + required: true + schema: + type: string + responses: + '204': + description: Task deleted + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a task + tags: + - Tasks + get: + operationId: GetTasksID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + description: Task details + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a task + tags: + - Tasks + patch: + description: Update a task. This will cancel all queued runs. + operationId: PatchTasksID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TaskUpdateRequest' + description: Task update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + description: Task updated + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a task + tags: + - Tasks + /api/v2/tasks/{taskID}/labels: + get: + operationId: GetTasksIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a task + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a task + tags: + - Tasks + post: + operationId: PostTasksIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: A list of all labels for a task + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a task + tags: + - Tasks + /api/v2/tasks/{taskID}/labels/{labelID}: + delete: + operationId: DeleteTasksIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + - description: The label ID. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Task not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label from a task + tags: + - Tasks + /api/v2/tasks/{taskID}/logs: + get: + operationId: GetTasksIDLogs + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Logs' + description: All logs for a task + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve all logs for a task + tags: + - Tasks + /api/v2/tasks/{taskID}/members: + get: + operationId: GetTasksIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMembers' + description: A list of users who have member privileges for a task + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all task members + tags: + - Tasks + post: + operationId: PostTasksIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as member + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMember' + description: Added to task members + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a member to a task + tags: + - Tasks + /api/v2/tasks/{taskID}/members/{userID}: + delete: + operationId: DeleteTasksIDMembersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the member to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '204': + description: Member removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove a member from a task + tags: + - Tasks + /api/v2/tasks/{taskID}/owners: + get: + operationId: GetTasksIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwners' + description: A list of users who have owner privileges for a task + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all owners of a task + tags: + - Tasks + post: + operationId: PostTasksIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as owner + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwner' + description: Added to task owners + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add an owner to a task + tags: + - Tasks + /api/v2/tasks/{taskID}/owners/{userID}: + delete: + operationId: DeleteTasksIDOwnersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the owner to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '204': + description: Owner removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove an owner from a task + tags: + - Tasks + /api/v2/tasks/{taskID}/runs: + get: + operationId: GetTasksIDRuns + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the task to get runs for. + in: path + name: taskID + required: true + schema: + type: string + - description: Returns runs after a specific ID. + in: query + name: after + schema: + type: string + - description: The number of runs to return + in: query + name: limit + schema: + default: 100 + maximum: 500 + minimum: 1 + type: integer + - description: Filter runs to those scheduled after this time, RFC3339 + in: query + name: afterTime + schema: + format: date-time + type: string + - description: Filter runs to those scheduled before this time, RFC3339 + in: query + name: beforeTime + schema: + format: date-time + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Runs' + description: A list of task runs + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List runs for a task + tags: + - Tasks + post: + operationId: PostTasksIDRuns + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: taskID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RunManually' + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Run' + description: Run scheduled to start + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Manually start a task run, overriding the current schedule + tags: + - Tasks + /api/v2/tasks/{taskID}/runs/{runID}: + delete: + operationId: DeleteTasksIDRunsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + - description: The run ID. + in: path + name: runID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Cancel a running task + tags: + - Tasks + get: + operationId: GetTasksIDRunsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + - description: The run ID. + in: path + name: runID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Run' + description: The run record + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a single run for a task + tags: + - Tasks + /api/v2/tasks/{taskID}/runs/{runID}/logs: + get: + operationId: GetTasksIDRunsIDLogs + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: ID of task to get logs for. + in: path + name: taskID + required: true + schema: + type: string + - description: ID of run to get logs for. + in: path + name: runID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Logs' + description: All logs for a run + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve all logs for a run + tags: + - Tasks + /api/v2/tasks/{taskID}/runs/{runID}/retry: + post: + operationId: PostTasksIDRunsIDRetry + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + - description: The run ID. + in: path + name: runID + required: true + schema: + type: string + requestBody: + content: + application/json; charset=utf-8: + schema: + type: object + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Run' + description: Run that has been queued + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retry a task run + tags: + - Tasks + /api/v2/telegraf/plugins: + get: + operationId: GetTelegrafPlugins + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The type of plugin desired. + in: query + name: type + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/TelegrafPlugins' + description: A list of Telegraf plugins. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all Telegraf plugins + tags: + - Telegraf Plugins + /api/v2/telegrafs: + get: + operationId: GetTelegrafs + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID the Telegraf config belongs to. + in: query + name: orgID + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Telegrafs' + description: A list of Telegraf configurations + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all Telegraf configurations + tags: + - Telegrafs + post: + operationId: PostTelegrafs + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TelegrafRequest' + description: Telegraf configuration to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Telegraf' + description: Telegraf configuration created + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a Telegraf configuration + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}: + delete: + operationId: DeleteTelegrafsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf configuration ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a Telegraf configuration + tags: + - Telegrafs + get: + operationId: GetTelegrafsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf configuration ID. + in: path + name: telegrafID + required: true + schema: + type: string + - in: header + name: Accept + required: false + schema: + default: application/toml + enum: + - application/toml + - application/json + - application/octet-stream + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Telegraf' + application/octet-stream: + example: |- + [agent] + interval = "10s" + schema: + type: string + application/toml: + example: |- + [agent] + interval = "10s" + schema: + type: string + description: Telegraf configuration details + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a Telegraf configuration + tags: + - Telegrafs + put: + operationId: PutTelegrafsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TelegrafRequest' + description: Telegraf configuration update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Telegraf' + description: An updated Telegraf configurations + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a Telegraf configuration + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/labels: + get: + operationId: GetTelegrafsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a Telegraf config + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a Telegraf config + tags: + - Telegrafs + post: + operationId: PostTelegrafsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The label added to the Telegraf config + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a Telegraf config + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/labels/{labelID}: + delete: + operationId: DeleteTelegrafsIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + - description: The label ID. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Telegraf config not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label from a Telegraf config + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/members: + get: + operationId: GetTelegrafsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMembers' + description: A list of Telegraf config members + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all users with member privileges for a Telegraf config + tags: + - Telegrafs + post: + operationId: PostTelegrafsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as member + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMember' + description: Member added to Telegraf config + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a member to a Telegraf config + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/members/{userID}: + delete: + operationId: DeleteTelegrafsIDMembersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the member to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '204': + description: Member removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove a member from a Telegraf config + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/owners: + get: + operationId: GetTelegrafsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf configuration ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwners' + description: Returns Telegraf configuration owners as a ResourceOwners list + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all owners of a Telegraf configuration + tags: + - Telegrafs + post: + operationId: PostTelegrafsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf configuration ID. + in: path + name: telegrafID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as owner + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwner' + description: >- + Telegraf configuration owner was added. Returns a ResourceOwner that + references the User. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add an owner to a Telegraf configuration + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/owners/{userID}: + delete: + operationId: DeleteTelegrafsIDOwnersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the owner to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '204': + description: Owner removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove an owner from a Telegraf config + tags: + - Telegrafs + /api/v2/templates/apply: + post: + description: Applies or performs a dry-run of template in an organization. + operationId: ApplyTemplate + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateApply' + application/x-jsonnet: + schema: + $ref: '#/components/schemas/TemplateApply' + text/yml: + schema: + $ref: '#/components/schemas/TemplateApply' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateSummary' + description: > + Success. The package dry-run succeeded. No new resources were + created. Returns a diff and summary of the dry-run. The diff and + summary won't contain IDs for resources that didn't exist at the + time of the dry-run. + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateSummary' + description: > + Success. The package applied successfully. Returns a diff and + summary of the run. The summary contains newly created resources. + The diff compares the initial state to the state after the package + applied. This corresponds to `"dryRun": true`. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Apply or dry-run a template + tags: + - Templates + /api/v2/templates/export: + post: + operationId: ExportTemplate + requestBody: + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/TemplateExportByID' + - $ref: '#/components/schemas/TemplateExportByName' + description: Export resources as an InfluxDB template. + required: false + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Template' + application/x-yaml: + schema: + $ref: '#/components/schemas/Template' + description: >- + The template was created successfully. Returns the newly created + template. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Export a new template + tags: + - Templates + /api/v2/users: + get: + operationId: GetUsers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/After' + - in: query + name: name + schema: + type: string + - in: query + name: id + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Users' + description: A list of users + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: List all users + tags: + - Users + post: + operationId: PostUsers + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/User' + description: User to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + description: User created + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Create a user + tags: + - Users + /api/v2/users/{userID}: + delete: + operationId: DeleteUsersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the user to delete. + in: path + name: userID + required: true + schema: + type: string + responses: + '204': + description: User deleted + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Delete a user + tags: + - Users + get: + operationId: GetUsersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The user ID. + in: path + name: userID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + description: User details + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Retrieve a user + tags: + - Users + patch: + operationId: PatchUsersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the user to update. + in: path + name: userID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/User' + description: User update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + description: User updated + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Update a user + tags: + - Users + /api/v2/users/{userID}/password: + post: + operationId: PostUsersIDPassword + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The user ID. + in: path + name: userID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PasswordResetBody' + description: New password + required: true + responses: + '204': + description: Password successfully updated + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unsuccessful authentication + security: + - BasicAuthentication: [] + summary: Update a password + tags: + - Users + /api/v2/variables: + get: + operationId: GetVariables + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The name of the organization. + in: query + name: org + schema: + type: string + - description: The organization ID. + in: query + name: orgID + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Variables' + description: A list of variables for an organization + '400': + $ref: '#/components/responses/ServerError' + description: Invalid request + default: + $ref: '#/components/responses/ServerError' + description: Internal server error + summary: List all variables + tags: + - Variables + post: + operationId: PostVariables + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable created + default: + $ref: '#/components/responses/ServerError' + description: Internal server error + summary: Create a variable + tags: + - Variables + /api/v2/variables/{variableID}: + delete: + operationId: DeleteVariablesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + responses: + '204': + description: Variable deleted + default: + $ref: '#/components/responses/ServerError' + description: Internal server error + summary: Delete a variable + tags: + - Variables + get: + operationId: GetVariablesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable found + '404': + $ref: '#/components/responses/ServerError' + description: Variable not found + default: + $ref: '#/components/responses/ServerError' + description: Internal server error + summary: Retrieve a variable + tags: + - Variables + patch: + operationId: PatchVariablesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable updated + default: + $ref: '#/components/responses/ServerError' + description: Internal server error + summary: Update a variable + tags: + - Variables + put: + operationId: PutVariablesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable to replace + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable updated + default: + $ref: '#/components/responses/ServerError' + description: Internal server error + summary: Replace a variable + tags: + - Variables + /api/v2/variables/{variableID}/labels: + get: + operationId: GetVariablesIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a variable + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a variable + tags: + - Variables + post: + operationId: PostVariablesIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The newly added label + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a variable + tags: + - Variables + /api/v2/variables/{variableID}/labels/{labelID}: + delete: + operationId: DeleteVariablesIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + - description: The label ID to delete. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Variable not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label from a variable + tags: + - Variables + /api/v2/write: + post: + description: > + Writes data to a bucket. + + + To write data into InfluxDB, you need the following: + + - **organization** – _See [View + organizations](https://docs.influxdata.com/influxdb/v2.1/organizations/view-orgs/#view-your-organization-id) + for instructions on viewing your organization ID._ + + - **bucket** – _See [View + buckets](https://docs.influxdata.com/influxdb/v2.1/organizations/buckets/view-buckets/) + for + instructions on viewing your bucket ID._ + - **API token** – _See [View + tokens](https://docs.influxdata.com/influxdb/v2.1/security/tokens/view-tokens/) + for instructions on viewing your API token._ + - **InfluxDB URL** – _See [InfluxDB + URLs](https://docs.influxdata.com/influxdb/v2.1/reference/urls/)_. + + - data in [line + protocol](https://docs.influxdata.com/influxdb/v2.1/reference/syntax/line-protocol) + format. + + + For more information and examples, see [Write data with the InfluxDB + API](https://docs.influxdata.com/influxdb/v2.1/write-data/developer-tools/api). + operationId: PostWrite + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: >- + When present, the header value tells the database that compression + is applied to the line protocol in the request body. + in: header + name: Content-Encoding + schema: + default: identity + description: >- + The header value specifies that the line protocol in the request + body is encoded with gzip or not encoded with identity. + enum: + - gzip + - identity + type: string + - description: >- + The header value indicates the format of the data in the request + body. + in: header + name: Content-Type + schema: + default: text/plain; charset=utf-8 + description: > + `text/plain` specifies line protocol. `UTF-8` is the default + character set. + enum: + - text/plain + - text/plain; charset=utf-8 + - application/vnd.influx.arrow + type: string + - description: >- + The header value indicates the size of the entity-body, in bytes, + sent to the database. If the length is greater than the database's + `max body` configuration option, the server responds with status + code `413`. + in: header + name: Content-Length + schema: + description: The length in decimal number of octets. + type: integer + - description: The header value specifies the response format. + in: header + name: Accept + schema: + default: application/json + description: The response format for errors. + enum: + - application/json + type: string + - description: >- + The parameter value specifies the destination organization for + writes. The database writes all points in the batch to this + organization. If you provide both `orgID` and `org` parameters, + `org` takes precedence. + in: query + name: org + required: true + schema: + description: Organization name or ID. + type: string + - description: >- + The parameter value specifies the ID of the destination organization + for writes. If both `orgID` and `org` are specified, `org` takes + precedence. + in: query + name: orgID + schema: + type: string + - description: The destination bucket for writes. + in: query + name: bucket + required: true + schema: + description: All points within batch are written to this bucket. + type: string + - description: The precision for the unix timestamps within the body line-protocol. + in: query + name: precision + schema: + $ref: '#/components/schemas/WritePrecision' + requestBody: + content: + text/plain: + schema: + format: byte + type: string + description: Data in line protocol format. + required: true + responses: + '204': + description: >- + InfluxDB validated the request data format and accepted the data for + writing to the bucket. `204` doesn't indicate a successful write + operation since writes are asynchronous. See [how to check for write + errors](https://docs.influxdata.com/influxdb/v2.1/write-data/troubleshoot). + '400': + content: + application/json: + examples: + measurementSchemaFieldTypeConflict: + summary: >- + Example of a field type conflict thrown by an explicit + bucket schema + value: + code: invalid + message: >- + partial write error (2 written): unable to parse + 'air_sensor,service=S1,sensor=L1 + temperature="90.5",humidity=70.0 1632850122': schema: + field type for field "temperature" not permitted by + schema; got String but expected Float + schema: + $ref: '#/components/schemas/LineProtocolError' + description: >- + Bad request. The line protocol data in the request is malformed. The + response body contains the first malformed line in the data. + InfluxDB rejected the batch and did not write any data. + '401': + content: + application/json: + examples: + tokenNotAuthorized: + summary: >- + Token is not authorized to access the organization or + resource + value: + code: unauthorized + message: unauthorized access + schema: + $ref: '#/components/schemas/Error' + description: | + Unauthorized. The error may indicate one of the following: + * The `Authorization: Token` header is missing or malformed. + * The API token value is missing from the header. + * The token does not have sufficient permissions to write to this organization and bucket. + '404': + content: + application/json: + examples: + resource-not-found: + summary: Not found error + value: + code: not found + message: bucket "air_sensor" not found + schema: + $ref: '#/components/schemas/Error' + description: >- + Not found. A requested resource was not found. The response body + contains the requested resource type, e.g. `organization name` or + `bucket`, and name. + '413': + content: + application/json: + schema: + $ref: '#/components/schemas/LineProtocolLengthError' + description: > + All request data was rejected and not written. InfluxDB OSS only + returns this error if the [Go (golang) + `ioutil.ReadAll()`](https://pkg.go.dev/io/ioutil#ReadAll) function + raises an error. + '500': + content: + application/json: + examples: + internalError: + summary: Internal error example + value: + code: internal error + schema: + $ref: '#/components/schemas/Error' + description: Internal server error. + '503': + description: >- + The server is temporarily unavailable to accept writes. The + `Retry-After` header describes when to try the write again. + headers: + Retry-After: + description: >- + A non-negative decimal integer indicating the seconds to delay + after the response is received. + schema: + format: int32 + type: integer + default: + $ref: '#/components/responses/ServerError' + summary: Write data + tags: + - Write +security: + - TokenAuthentication: [] + - BasicAuthentication: [] + - QuerystringAuthentication: [] +servers: + - url: / +tags: + - description: > + Use one of the following schemes to authenticate to the InfluxDB API: + + - [Token authentication](#section/Authentication/TokenAuthentication) + + - [Basic authentication](#section/Authentication/BasicAuthentication) + + - [Querystring + authentication](#section/Authentication/QuerystringAuthentication) + + + name: Authentication + x-traitTag: true + - description: > + Create and manage API tokens. An **authorization** associates a list of + permissions to an **organization** and provides a token for API access. + Optionally, you can restrict an authorization and its token to a specific + user. + + + For more information and examples, see the following: + - [Use tokens in API requests](https://docs.influxdata.com/influxdb/v2.1/api-guide/api_intro/#authentication). + - [Manage API tokens](https://docs.influxdata.com/influxdb/v2.1/security/tokens). + - [Assign a token to a specific user](https://docs.influxdata.com/influxdb/v2.1/security/tokens/create-token). + name: Authorizations + - Backup + - Buckets + - Cells + - Checks + - Dashboards + - DBRPs + - Delete + - Health + - Labels + - Legacy Authorizations + - NotificationEndpoints + - NotificationRules + - Organizations + - Ping + - description: | + Retrieve data, analyze queries, and get query suggestions. + name: Query + - description: > + See the [**API Quick + Start**](https://docs.influxdata.com/influxdb/v2.1/api-guide/api_intro/) + to get up and running authenticating with tokens, writing to buckets, and + querying data. + + + [**InfluxDB API client + libraries**](https://docs.influxdata.com/influxdb/v2.1/api-guide/client-libraries/) + are available for popular languages and ready to import into your + application. + name: Quick start + x-traitTag: true + - Ready + - Resources + - description: > + The InfluxDB API uses standard HTTP status codes for success and failure + responses. + + The response body may include additional details. For details about a + specific operation's response, see **Responses** and **Response Samples** + for that operation. + + + API operations may return the following HTTP status codes: + + + |  Code  | Status | Description | + + |:-----------:|:------------------------ |:--------------------- | + + | `200` | Success | | + + | `204` | No content | For a `POST` request, `204` + indicates that InfluxDB accepted the request and request data is valid. + Asynchronous operations, such as `write`, might not have completed yet. | + + | `400` | Bad request | `Authorization` header is + missing or malformed or the API token does not have permission for the + operation. | + + | `401` | Unauthorized | May indicate one of the + following:
  • `Authorization: Token` header is missing or + malformed
  • API token value is missing from the header
  • API + token does not have permission. For more information about token types and + permissions, see [Manage API + tokens](https://docs.influxdata.com/influxdb/v2.1/security/tokens/)
    • | + + | `404` | Not found | Requested resource was not + found. `message` in the response body provides details about the requested + resource. | + + | `413` | Request entity too large | Request payload exceeds the + size limit. | + + | `422` | Unprocessible entity | Request data is invalid. `code` + and `message` in the response body provide details about the problem. | + + | `429` | Too many requests | API token is temporarily over + the request quota. The `Retry-After` header describes when to try the + request again. | + + | `500` | Internal server error | | + + | `503` | Service unavailable | Server is temporarily + unavailable to process the request. The `Retry-After` header describes + when to try the request again. | + name: Response codes + x-traitTag: true + - Restore + - Routes + - Rules + - Scraper Targets + - Secrets + - Setup + - Signin + - Signout + - Sources + - Tasks + - Telegraf Plugins + - Telegrafs + - Templates + - Users + - Variables + - Views + - description: | + Write time series data to buckets. + name: Write +x-tagGroups: + - name: Overview + tags: + - Quick start + - Authentication + - Response codes + - name: Data I/O endpoints + tags: + - Write + - Query + - name: Resource endpoints + tags: + - Buckets + - Dashboards + - Tasks + - Resources + - name: Security and access endpoints + tags: + - Authorizations + - Organizations + - Users + - name: System information endpoints + tags: + - Health + - Ping + - Ready + - Routes + - name: All endpoints + tags: + - Authorizations + - Backup + - Buckets + - Cells + - Checks + - Dashboards + - DBRPs + - Delete + - Health + - Labels + - Legacy Authorizations + - NotificationEndpoints + - NotificationRules + - Organizations + - Ping + - Query + - Ready + - Resources + - Restore + - Routes + - Rules + - Scraper Targets + - Secrets + - Setup + - Signin + - Signout + - Sources + - Tasks + - Telegraf Plugins + - Telegrafs + - Templates + - Users + - Variables + - Views + - Write diff --git a/api-docs/v2.1/swaggerV1Compat.yml b/api-docs/v2.1/swaggerV1Compat.yml new file mode 100644 index 0000000000..583c4b0d88 --- /dev/null +++ b/api-docs/v2.1/swaggerV1Compat.yml @@ -0,0 +1,329 @@ +# this is a manually maintained file for these old routes until oats#15 is resolved +openapi: "3.0.0" +info: + title: Influx API Service (V1 compatible endpoints) + version: 0.1.0 +servers: + - url: / + description: V1 compatible api endpoints. +paths: + /write: + post: # technically this functions with other methods as well + operationId: PostWriteV1 + tags: + - Write + summary: Write time series data into InfluxDB in a V1 compatible format + requestBody: + description: Line protocol body + required: true + content: + text/plain: + schema: + type: string + parameters: + - $ref: "#/components/parameters/TraceSpan" + - $ref: "#/components/parameters/AuthUserV1" + - $ref: "#/components/parameters/AuthPassV1" + - in: query + name: db + schema: + type: string + required: true + description: The bucket to write to. If the specified bucket does not exist, a bucket is created with a default 3 day retention policy. + - in: query + name: rp + schema: + type: string + description: The retention policy name. + - in: query + name: precision + schema: + type: string + description: Write precision. + - in: header + name: Content-Encoding + description: When present, its value indicates to the database that compression is applied to the line-protocol body. + schema: + type: string + description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity. + default: identity + enum: + - gzip + - identity + responses: + "204": + description: Write data is correctly formatted and accepted for writing to the bucket. + "400": + description: Line protocol was not in correct format, and no points were written. Response can be used to determine the first malformed line in the line-protocol body. All data in body was rejected and not written. + content: + application/json: + schema: + $ref: "#/components/schemas/LineProtocolError" + "401": + description: Token does not have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "403": + description: No token was sent and they are required. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "413": + description: Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written. + content: + application/json: + schema: + $ref: "#/components/schemas/LineProtocolLengthError" + "429": + description: Token is temporarily over quota. The Retry-After header describes when to try the write again. + headers: + Retry-After: + description: A non-negative decimal integer indicating the seconds to delay after the response is received. + schema: + type: integer + format: int32 + "503": + description: Server is temporarily unavailable to accept writes. The Retry-After header describes when to try the write again. + headers: + Retry-After: + description: A non-negative decimal integer indicating the seconds to delay after the response is received. + schema: + type: integer + format: int32 + default: + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /query: + post: # technically this functions with other methods as well + operationId: PostQueryV1 + tags: + - Query + summary: Query InfluxDB in a V1 compatible format + requestBody: + description: InfluxQL query to execute. + content: + text/plain: # although this should be `application/vnd.influxql`, oats breaks so we define the content-type header parameter + schema: + type: string + parameters: + - $ref: "#/components/parameters/TraceSpan" + - $ref: "#/components/parameters/AuthUserV1" + - $ref: "#/components/parameters/AuthPassV1" + - in: header + name: Accept + schema: + type: string + description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps. + default: application/json + enum: + - application/json + - application/csv + - text/csv + - application/x-msgpack + - in: header + name: Accept-Encoding + description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand. + schema: + type: string + description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity. + default: identity + enum: + - gzip + - identity + - in: header + name: Content-Type + schema: + type: string + enum: + - application/vnd.influxql + - in: query + name: q + description: Defines the influxql query to run. + schema: + type: string + responses: + "200": + description: Query results + headers: + Content-Encoding: + description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body + schema: + type: string + description: Specifies that the response in the body is encoded with gzip or not encoded with identity. + default: identity + enum: + - gzip + - identity + Trace-Id: + description: The Trace-Id header reports the request's trace ID, if one was generated. + schema: + type: string + description: Specifies the request's trace ID. + content: + application/csv: + schema: + $ref: "#/components/schemas/InfluxQLCSVResponse" + text/csv: + schema: + $ref: "#/components/schemas/InfluxQLCSVResponse" + application/json: + schema: + $ref: "#/components/schemas/InfluxQLResponse" + application/x-msgpack: + schema: + type: string + format: binary + "429": + description: Token is temporarily over quota. The Retry-After header describes when to try the read again. + headers: + Retry-After: + description: A non-negative decimal integer indicating the seconds to delay after the response is received. + schema: + type: integer + format: int32 + default: + description: Error processing query + content: + application/json: + schema: + $ref: "#/components/schemas/Error" +components: + parameters: + TraceSpan: + in: header + name: Zap-Trace-Span + description: OpenTracing span context + example: + trace_id: "1" + span_id: "1" + baggage: + key: value + required: false + schema: + type: string + AuthUserV1: + in: query + name: u + required: false + schema: + type: string + description: Username. + AuthPassV1: + in: query + name: p + required: false + schema: + type: string + description: User token. + schemas: + InfluxQLResponse: + properties: + results: + type: array + items: + type: object + properties: + statement_id: + type: integer + series: + type: array + items: + type: object + properties: + name: + type: string + columns: + type: array + items: + type: integer + values: + type: array + items: + type: array + items: {} + InfluxQLCSVResponse: + type: string + example: > + name,tags,time,test_field,test_tag + test_measurement,,1603740794286107366,1,tag_value + test_measurement,,1603740870053205649,2,tag_value + test_measurement,,1603741221085428881,3,tag_value + Error: + properties: + code: + description: Code is the machine-readable error code. + readOnly: true + type: string + # This set of enumerations must remain in sync with the constants defined in errors.go + enum: + - internal error + - not found + - conflict + - invalid + - unprocessable entity + - empty value + - unavailable + - forbidden + - too many requests + - unauthorized + - method not allowed + message: + readOnly: true + description: Message is a human-readable message. + type: string + required: [code, message] + LineProtocolError: + properties: + code: + description: Code is the machine-readable error code. + readOnly: true + type: string + enum: + - internal error + - not found + - conflict + - invalid + - empty value + - unavailable + message: + readOnly: true + description: Message is a human-readable message. + type: string + op: + readOnly: true + description: Op describes the logical code operation during error. Useful for debugging. + type: string + err: + readOnly: true + description: Err is a stack of errors that occurred during processing of the request. Useful for debugging. + type: string + line: + readOnly: true + description: First line within sent body containing malformed data + type: integer + format: int32 + required: [code, message, op, err] + LineProtocolLengthError: + properties: + code: + description: Code is the machine-readable error code. + readOnly: true + type: string + enum: + - invalid + message: + readOnly: true + description: Message is a human-readable message. + type: string + maxLength: + readOnly: true + description: Max length in bytes for a body of line-protocol. + type: integer + format: int32 + required: [code, message, maxLength] diff --git a/assets/styles/layouts/_api-overrides.scss b/assets/styles/layouts/_api-overrides.scss index e9a65eb0a1..ac99fc5d49 100644 --- a/assets/styles/layouts/_api-overrides.scss +++ b/assets/styles/layouts/_api-overrides.scss @@ -1,9 +1,9 @@ @import "tools/color-palette"; -@import "tools/icomoon"; +@import "tools/icomoon-v2"; // Fonts $rubik: 'Rubik', sans-serif; -$roboto-mono: 'Roboto Mono', monospace; +$code: 'IBM Plex Mono', monospace;; // Font weights $medium: 500; @@ -60,7 +60,7 @@ $bold: 700; } &:before { content: "\e919"; - font-family: 'icomoon'; + font-family: 'icomoon-v2'; margin-right: .65rem; } } @@ -77,7 +77,7 @@ $bold: 700; display: inline-block; font-size: .95rem; margin-right: .5rem; - font-family: 'icomoon'; + font-family: 'icomoon-v2'; } &:hover { color: $g20-white; @@ -156,14 +156,14 @@ $bold: 700; } .redoc-json { - font-family: $roboto-mono !important; + font-family: $code !important; } // Inline Code .flfxUM code, .gDsWLk code, .kTVySD { - font-family: $roboto-mono !important; + font-family: $code !important; color: $cp-marguerite; background: $cp-titan; border-color: $cp-titan; @@ -275,7 +275,7 @@ $bold: 700; background-color: $g2-kevlar; font-family: $rubik; } -.iENVAs { font-family: $roboto-mono; } +.iENVAs { font-family: $code; } .dpMbau { font-family: $rubik; } // Code controls @@ -285,7 +285,7 @@ $bold: 700; } // Code blocks -.kZHJcC { font-family: $roboto-mono; } +.kZHJcC { font-family: $code; } .jCgylq { .token.string { color: $gr-honeydew; diff --git a/assets/styles/layouts/_article.scss b/assets/styles/layouts/_article.scss index d8a950efa7..a6ff04ce6f 100644 --- a/assets/styles/layouts/_article.scss +++ b/assets/styles/layouts/_article.scss @@ -22,7 +22,6 @@ & + pre { margin-top: .5rem } & + .code-tabs-wrapper { margin-top: 0; } } - .title { margin-bottom: 2.65rem; } h1 { font-weight: normal; font-size: 2.65rem; @@ -128,6 +127,7 @@ "article/tables", "article/tags", "article/telegraf-plugins", + "article/title", "article/truncate", "article/video", "article/warn"; @@ -185,6 +185,12 @@ } .nowrap { white-space: nowrap } + .all-caps { + text-transform: uppercase; + font-size: .95rem; + letter-spacing: .07em; + font-weight: $medium !important; + } /////////////////////////// Getting Started Buttons ////////////////////////// @@ -213,10 +219,6 @@ .article { padding: 1.5rem 1.5rem 3rem; - .title { - margin-bottom: 2rem; - h1 { margin: .35em 0 .2em; font-size: 2.4rem; } - } h2 { font-size: 1.9rem; } h3 { font-size: 1.55rem; } h4 { font-size: 1.3rem; } diff --git a/assets/styles/layouts/_error-page.scss b/assets/styles/layouts/_error-page.scss index 0743af4d8f..6b86c8932c 100644 --- a/assets/styles/layouts/_error-page.scss +++ b/assets/styles/layouts/_error-page.scss @@ -72,7 +72,7 @@ &.back:before { content: "\e90a"; - font-family: "icomoon"; + font-family: "icomoon-v2"; margin-right: .35rem; vertical-align: text-top; } diff --git a/assets/styles/layouts/_global.scss b/assets/styles/layouts/_global.scss index 895aa26da0..786a5adb99 100644 --- a/assets/styles/layouts/_global.scss +++ b/assets/styles/layouts/_global.scss @@ -1,5 +1,5 @@ $rubik: 'Rubik', sans-serif; -$roboto-mono: 'Roboto Mono', monospace; +$code: 'IBM Plex Mono', monospace;; // Font weights $medium: 500; diff --git a/assets/styles/layouts/_inline-icons.scss b/assets/styles/layouts/_inline-icons.scss index e4b45a2931..a67acf95c0 100644 --- a/assets/styles/layouts/_inline-icons.scss +++ b/assets/styles/layouts/_inline-icons.scss @@ -9,7 +9,7 @@ &.large:before { font-size: 1.1rem; } &.add-btn-round { - font-family: "icomoon"; + font-family: "icomoon-v2"; color:#fff; background: linear-gradient(45deg,#5c10a0,#8e1fc3); border-radius:50%; @@ -21,6 +21,16 @@ height: 20px; padding-left: .29rem; line-height: 1.25rem; + + &.v3 { + position: relative; + background: $g5-pepper; + width: 18px; + height: 18px; + font-size: .65rem; + line-height: 0rem; + padding: 9px 0 0 4px; + } } &.ui-toggle { @@ -45,6 +55,16 @@ top: 4px; right: 4px; } + + &.v3 { + width: 26px; + .circle { + height: 12px; + width: 12px; + top: 2px; + right: 2px; + } + } } } @@ -200,10 +220,96 @@ } } } + + ///////////////////////////////// CLOCKFACE V3 ///////////////////////////////// } +.nav-items-v3 { + .nav-item-v3 { + display: inline-flex; + align-items: center; + margin: 0 1rem 1.25rem 0; + max-width: 225px; + background: linear-gradient(rgba(#052943, .9), rgba(#062238, .9)); + color: $g20-white; + height: 60px; + border-radius: $radius; + + &.account { + padding: 8px; + + .acct-inner-v3 { + display: flex; + background-color: #f1f1f30d; + border-radius: $radius; + } + + .acct-icon-v3 { + display: flex; + align-content: center; + justify-content: center; + font-weight: bold; + width: 44px; + height: 44px; + @include gradient($grad-Miyazakisky, 54deg); + border-radius: $radius; + + .initial { + align-self: center; + } + } + + .acct-label-v3 { + display: inline-block; + padding: 5px 0px 0px 8px; + width: 165px; + + .username { + font-size: .75rem; + font-weight: 500; + color: #9e9ead; + } + .orgname { + font-size: .85rem; + line-height: 1.1rem; + } + } + + } + } + + .nav-icon-v3 { + display: flex; + justify-content: center; + align-items: center; + height: 100%; + width: 60px; + flex-shrink: 0; + } + + p.nav-label-v3 { + display: inline-block; + margin: 0; + padding: 0; + font-weight: 500; + font-size: 1.15rem; + min-width: 225px; + color: $g20-white; + } + + .cf-icon { + display: inline-block; + font-size: 1.35rem; + } + +} + + +//////////////////////////////////////////////////////////////////////////////// ///////////////////////////////// MEDIA QUERIES //////////////////////////////// +//////////////////////////////////////////////////////////////////////////////// @include media(small) { - .article--content .nav-item:nth-child(2) {display: none;} + .article--content.nav-item:nth-child(2) {display: none;} + .article--content.nav-item-v3:nth-child(2) {display: none;} } diff --git a/assets/styles/layouts/_sidebar-toggle.scss b/assets/styles/layouts/_sidebar-toggle.scss index cac354039e..d103727152 100644 --- a/assets/styles/layouts/_sidebar-toggle.scss +++ b/assets/styles/layouts/_sidebar-toggle.scss @@ -28,7 +28,7 @@ $vertical-offset: -14px; } & > a { - font-family: "icomoon"; + font-family: "icomoon-v2"; color: rgba($article-text, .5); text-decoration: none; } diff --git a/assets/styles/layouts/_sidebar.scss b/assets/styles/layouts/_sidebar.scss index f328b8a646..85cbeb8b3b 100644 --- a/assets/styles/layouts/_sidebar.scss +++ b/assets/styles/layouts/_sidebar.scss @@ -11,7 +11,7 @@ &:after { content: "\e905"; display: block; - font-family: 'icomoon'; + font-family: 'icomoon-v2'; position: absolute; top: .15rem; right: .25rem; @@ -167,46 +167,7 @@ text-decoration: none; font-weight: $medium; display: inline-block; - - /////////////////////// Product exclusivity labels /////////////////////// - span:after{ - display: inline-block; - position: relative; - top: -2px; - margin-left: .15rem; - padding: .45rem .18rem .35rem; - line-height: 0; - font-size: .6rem; - font-style: italic; - border-radius: 8px; - } - - .cloud { - &:after { - content: "CLOUD"; - color: $product-cloud; - border: 1px solid rgba($product-cloud, .5); - background: rgba($product-cloud, .1); - } - } - .oss { - &:after { - content: "OSS"; - color: $product-oss; - border: 1px solid rgba($product-oss, .5); - background: rgba($product-oss, .1); - } - } - .enterprise { - &:after { - content: "ENT"; - color: $product-enterprise; - border: 1px solid rgba($product-enterprise, .5); - background: rgba($product-enterprise, .1); - } - } } - ////////////////////// End Product exclusivity labels ////////////////////// .nav-category > a { color: $nav-category; @@ -277,7 +238,7 @@ // Nav section title styles h4 { margin: 2rem 0 0 -1rem; - color: rgba($article-heading-alt, .6); + color: rgba($article-heading-alt, .5); font-style: italic; font-weight: 700; text-transform: uppercase; @@ -287,7 +248,7 @@ &.platform, &.flux { &:after { content: "\e911"; - font-family: "icomoon"; + font-family: "icomoon-v2"; font-style: normal; font-size: 1rem; opacity: .4; diff --git a/assets/styles/layouts/_top-nav.scss b/assets/styles/layouts/_top-nav.scss index 0f5c99cdf5..2e65bde152 100644 --- a/assets/styles/layouts/_top-nav.scss +++ b/assets/styles/layouts/_top-nav.scss @@ -7,7 +7,7 @@ z-index: 1; .influx-home { - font-family: 'icomoon'; + font-family: 'icomoon-v2'; font-size: 1.9rem; color: $topnav-link; text-decoration: none; @@ -76,7 +76,7 @@ &:after { content: "\e918"; - font-family: 'icomoon'; + font-family: 'icomoon-v2'; position: absolute; top: .45rem; right: .4rem; @@ -137,7 +137,7 @@ position: relative; &:after { content: "\e911"; - font-family: "icomoon"; + font-family: "icomoon-v2"; position: absolute; opacity: .4; margin-left: .25rem; @@ -154,7 +154,6 @@ .theme-switcher, #search-btn, .url-trigger { display: inline-block; padding: 0; - font-size: 1.8rem; line-height: 0; color: rgba($topnav-link, .5); background: none; @@ -171,8 +170,8 @@ color: rgba($topnav-link, 1); cursor: pointer; } - &#theme-switch-dark { display: $theme-switch-dark; } - &#theme-switch-light { display: $theme-switch-light; } + &#theme-switch-dark { display: $theme-switch-dark; font-size: 1.15rem; } + &#theme-switch-light { display: $theme-switch-light; font-size: 1.3rem; } } .url-trigger { diff --git a/assets/styles/layouts/_url-selector.scss b/assets/styles/layouts/_url-selector.scss index 67ba6b738d..fcbd9e83e8 100644 --- a/assets/styles/layouts/_url-selector.scss +++ b/assets/styles/layouts/_url-selector.scss @@ -332,7 +332,7 @@ label:after { content: "\e924"; display: inline-block; margin-right: .35rem; - font-family: "icomoon"; + font-family: "icomoon-v2"; font-style: normal; font-size: .8rem; } diff --git a/assets/styles/layouts/article/_buttons.scss b/assets/styles/layouts/article/_buttons.scss index 39bdedfce3..bb99b08726 100644 --- a/assets/styles/layouts/article/_buttons.scss +++ b/assets/styles/layouts/article/_buttons.scss @@ -4,7 +4,7 @@ a.btn { position: relative; display: inline-block; margin: .5rem .25rem .5rem 0; - padding: .5rem 1rem; + padding: 0.85rem 1.5rem; color: $article-btn-text !important; border-radius: $radius; font-size: .95rem; @@ -36,14 +36,14 @@ a.btn { &.download:before { content: "\e91d"; - font-family: "icomoon"; + font-family: "icomoon-v2"; margin-right: .5rem; font-size: 1.1rem; } &.github:before { content: "\eab0"; - font-family: "icomoon"; + font-family: "icomoon-v2"; margin-right: .5rem; font-size: 1.1rem; } diff --git a/assets/styles/layouts/article/_children.scss b/assets/styles/layouts/article/_children.scss index 092e220016..3d9a6f9607 100644 --- a/assets/styles/layouts/article/_children.scss +++ b/assets/styles/layouts/article/_children.scss @@ -6,7 +6,7 @@ a a:after { content: "\e91a"; - font-family: "icomoon"; + font-family: "icomoon-v2"; color: rgba($article-heading, .35); vertical-align: bottom; transition: color .2s; diff --git a/assets/styles/layouts/article/_code.scss b/assets/styles/layouts/article/_code.scss index 11b5f6e577..b88fe081e0 100644 --- a/assets/styles/layouts/article/_code.scss +++ b/assets/styles/layouts/article/_code.scss @@ -2,7 +2,7 @@ code,pre { background: $article-code-bg; - font-family: $roboto-mono; + font-family: $code; color: $article-code; } diff --git a/assets/styles/layouts/article/_feedback.scss b/assets/styles/layouts/article/_feedback.scss index 792c32c989..7d9f5c1bc2 100644 --- a/assets/styles/layouts/article/_feedback.scss +++ b/assets/styles/layouts/article/_feedback.scss @@ -33,7 +33,7 @@ color: $article-heading-alt; margin: 0 .25rem 0 -.25rem; font-size: 1.65rem; - font-family: 'icomoon'; + font-family: 'icomoon-v2'; vertical-align: middle; } &.slack:before { @@ -54,7 +54,7 @@ a { display: block; - padding-left: .7rem; + padding-left: 1rem; font-size: .85rem; &.btn { @@ -69,8 +69,8 @@ &:before { display: inline-block; - margin-right: .5rem; - font-family: 'icomoon'; + margin-right: .7rem; + font-family: 'icomoon-v2'; } &.edit:before { diff --git a/assets/styles/layouts/article/_flux.scss b/assets/styles/layouts/article/_flux.scss index 3d51df11fd..857fa8b307 100644 --- a/assets/styles/layouts/article/_flux.scss +++ b/assets/styles/layouts/article/_flux.scss @@ -1,16 +1,5 @@ //////////////////////// Styles unique to the Flux docs //////////////////////// -.title .meta { - margin-bottom: 0; - padding: 0 .65em 0 .75em; - color: $article-heading; - background: rgba($article-heading, .07); - font-size: .9rem; - font-weight: $medium; - border-radius: 1em; - display: inline-block; -} - h2,h3,h4 { &:after { content: attr(data-type); diff --git a/assets/styles/layouts/article/_html-diagrams.scss b/assets/styles/layouts/article/_html-diagrams.scss index aeebd44646..c467e1f7f2 100644 --- a/assets/styles/layouts/article/_html-diagrams.scss +++ b/assets/styles/layouts/article/_html-diagrams.scss @@ -4,7 +4,7 @@ display: inline-block; margin: 1rem 0 2rem; padding: 1.5rem 2.5rem 1.5rem 1.5rem; - font-family: $roboto-mono; + font-family: $code; border-radius: $radius; box-shadow: 1px 3px 10px $article-shadow; & > ul { padding: 0; margin: 0; diff --git a/assets/styles/layouts/article/_pagination-btns.scss b/assets/styles/layouts/article/_pagination-btns.scss index 4e623f2a6e..7f44860f73 100644 --- a/assets/styles/layouts/article/_pagination-btns.scss +++ b/assets/styles/layouts/article/_pagination-btns.scss @@ -17,7 +17,7 @@ &:before { content: "\e90a"; display: inline-block; - font-family: "icomoon"; + font-family: "icomoon-v2"; margin-right: .5rem; vertical-align: middle; } @@ -29,7 +29,7 @@ &:before { content: "\e90c"; display: inline-block; - font-family: "icomoon"; + font-family: "icomoon-v2"; margin-left: .5rem; vertical-align: middle; } diff --git a/assets/styles/layouts/article/_svgs.scss b/assets/styles/layouts/article/_svgs.scss index 0eda1c2745..2f8d0d316f 100644 --- a/assets/styles/layouts/article/_svgs.scss +++ b/assets/styles/layouts/article/_svgs.scss @@ -1,23 +1,5 @@ svg { - &#join-vs-union { - max-width: 525px; - width: 100%; - margin-bottom: 2rem; - - .st0{fill: $svg-table-code-bg;} - .st1{fill: $svg-table-header;} - .st2{fill: $svg-table-row-alt1;} - .st3{fill:none;stroke: $svg-table-stroke;stroke-width:2;stroke-miterlimit:10;} - .st4{fill:none;stroke: $svg-table-stroke;stroke-width:4;stroke-miterlimit:10;} - .st5{fill: $svg-table-row-alt2;} - .st6{fill: $svg-table-code;} - .st7{font-family:'Roboto Mono';} - .st8{font-size:14.2px;} - .st9{fill: $svg-table-code-operator;} - .st10{fill: $svg-table-code-string;} - } - &[id^='geo-s2-cells-'] { max-width: 250px; .geo-cell{fill:rgba($svg-geo-s2-cell, 0.25);stroke:$svg-geo-s2-cell;stroke-width:3;stroke-linejoin:round;stroke-miterlimit:10;} diff --git a/assets/styles/layouts/article/_tabbed-content.scss b/assets/styles/layouts/article/_tabbed-content.scss index 450169d6ef..3be7ebb486 100644 --- a/assets/styles/layouts/article/_tabbed-content.scss +++ b/assets/styles/layouts/article/_tabbed-content.scss @@ -14,7 +14,7 @@ position: relative; font-size: 0.875rem; font-weight: $medium; - padding: .35rem .75rem; + padding: .65rem 1.25rem; display: inline-block; text-align: center; color: $article-tab-text !important; @@ -56,7 +56,7 @@ p { justify-content: flex-start; } a { flex-grow: unset; - padding: 0rem .5rem; + padding: .35rem 1rem; } } } diff --git a/assets/styles/layouts/article/_title.scss b/assets/styles/layouts/article/_title.scss new file mode 100644 index 0000000000..217f59b4e9 --- /dev/null +++ b/assets/styles/layouts/article/_title.scss @@ -0,0 +1,35 @@ +////////////// Styles for the title block at the top of each page ////////////// + +.title { + margin-bottom: 2.65rem; + + .meta { + margin-bottom: 0; + padding: 0 .65em 0 .75em; + color: $article-heading; + background: rgba($article-heading, .07); + font-size: .9rem; + font-weight: $medium; + border-radius: 1em; + display: inline-block; + + &.updated-in { + padding: 0 0 0 .4em; + background: none; + font-weight: normal; + font-style: italic; + color: rgba($article-heading, .6) + } + } +} + +//////////////////////////////////////////////////////////////////////////////// +///////////////////////////////// MEDIA QUERIES //////////////////////////////// +//////////////////////////////////////////////////////////////////////////////// + +@include media(small) { + .title { + margin-bottom: 2rem; + h1 { margin: .35em 0 .2em; font-size: 2.4rem; } + } +} \ No newline at end of file diff --git a/assets/styles/layouts/article/_warn.scss b/assets/styles/layouts/article/_warn.scss index d3ed135f8b..89af33a2e8 100644 --- a/assets/styles/layouts/article/_warn.scss +++ b/assets/styles/layouts/article/_warn.scss @@ -1,6 +1,6 @@ .warn { border-color: $article-warn-base; - background: rgba($article-warn-base, .08); + background: $article-warn-bg; h1,h2,h3,h4,h5,h6 { color: $article-warn-heading; } diff --git a/assets/styles/styles-default.scss b/assets/styles/styles-default.scss index 36e7f67984..7be4055d32 100644 --- a/assets/styles/styles-default.scss +++ b/assets/styles/styles-default.scss @@ -1,7 +1,8 @@ // InfluxData Docs Default Theme (Light) // Import Tools -@import "tools/icomoon", +@import "tools/icomoon-v2", + "tools/icon", "tools/media-queries.scss", "tools/mixins.scss", "tools/tooltips", diff --git a/assets/styles/themes/_theme-dark.scss b/assets/styles/themes/_theme-dark.scss index 83d0ed6558..df9c6ec214 100644 --- a/assets/styles/themes/_theme-dark.scss +++ b/assets/styles/themes/_theme-dark.scss @@ -14,7 +14,7 @@ @import "tools/color-palette"; -$body-bg: $g0-obsidian; +$body-bg: $grey5; // TopNav Colors $topnav-link: $g20-white; @@ -24,7 +24,7 @@ $theme-switch-light: inline-block; $theme-switch-dark: none; // Search -$sidebar-search-bg: $g2-kevlar; +$sidebar-search-bg: $grey15; $sidebar-search-shadow: rgba($g0-obsidian, .05); $sidebar-search-highlight: $b-pool; $sidebar-search-text: $g20-white; @@ -34,7 +34,7 @@ $nav-category: $b-pool; $nav-category-hover: $g20-white; $nav-item: $g15-platinum; $nav-item-hover: $b-pool; -$nav-border: $g5-pepper; +$nav-border: $grey25; $nav-toggle: $g16-pearl; $nav-toggle-hover: $g16-pearl; $nav-toggle-bg-hover: $b-pool; @@ -46,7 +46,7 @@ $product-oss: $p-potassium; $product-enterprise: $br-galaxy; // Article Content -$article-bg: $g1-raven; +$article-bg: $grey10; $article-heading: $g20-white; $article-heading-alt: $g19-ghost; $article-text: $g15-platinum; @@ -54,11 +54,11 @@ $article-bold: $g19-ghost; $article-link: $b-pool; $article-link-hover: $g20-white; $article-hr: $g5-pepper; -$article-shadow: $g0-obsidian; +$article-shadow: $grey5; // Article Code $article-code: $cp-munchkin; -$article-code-bg: $g0-obsidian; +$article-code-bg: $grey5; $article-code-shadow: $g0-obsidian; $article-code-accent1: $g7-graphite; $article-code-accent2: $b-pool; @@ -74,7 +74,7 @@ $article-code-scrollbar: $g3-castle; // Article Tables $article-table-header: $grad-GundamPilot; -$article-table-row-alt: $g3-castle; +$article-table-row-alt: $grey20; $article-table-scrollbar: $g0-obsidian; // Article Notes, Warnings, & Messages @@ -89,7 +89,7 @@ $article-note-table-row-alt: #1a3c34; $article-note-table-scrollbar: #162627; $article-note-shadow: $g0-obsidian; $article-note-code: $br-galaxy; -$article-note-code-bg: #0d1617; +$article-note-code-bg: #040d0e; $article-note-code-accent1: #567375; $article-note-code-accent2: $b-pool; $article-note-code-accent3: $gr-viridian; @@ -100,6 +100,7 @@ $article-note-code-accent7: #e90; $article-note-code-scrollbar: #162627; $article-warn-base: $r-dreamsicle; +$article-warn-bg: #ff61851a; $article-warn-heading: $g20-white; $article-warn-text: $r-tungsten; $article-warn-link: $r-marmelade; @@ -107,9 +108,9 @@ $article-warn-link-hover: $g20-white; $article-warn-table-header: $grad-red; $article-warn-table-row-alt: #4a2a2a; $article-warn-table-scrollbar: #1f181b; -$article-warn-shadow: $g0-obsidian; +$article-warn-shadow: #0d0610; $article-warn-code: #ec6e6e; -$article-warn-code-bg: $g0-obsidian; +$article-warn-code-bg: #0d0610; $article-warn-code-accent1: #844c4c; $article-warn-code-accent2: $b-pool; $article-warn-code-accent3: $gr-viridian; @@ -129,7 +130,7 @@ $article-cloud-table-row-alt: #1b3a58; $article-cloud-table-scrollbar: #192a3a; $article-cloud-shadow: $g0-obsidian; $article-cloud-code: $b-laser; -$article-cloud-code-bg: #110d2b; +$article-cloud-code-bg: #0a071c; $article-cloud-code-accent1: #567375; $article-cloud-code-accent2: $b-pool; $article-cloud-code-accent3: $gr-viridian; @@ -146,7 +147,7 @@ $article-enterprise-link-hover: $g20-white; // Article Tabs for tabbed content $article-tab-text: $g12-forge; -$article-tab-bg: $g0-obsidian; +$article-tab-bg: $grey5; $article-tab-active-text: $g20-white; $article-tab-active-bg: $b-pool; @@ -180,7 +181,7 @@ $landing-btn-grad-hover: $grad-blue-light; // Home page colors $home-btn-gradient: $grad-NineteenEightyFour; $home-btn-gradient-hover: $grad-PastelGothic; -$home-tick-bg-gradient: $grad-grey-abyss; +$home-tick-bg-gradient: $grad-cool-grey-abyss; $default-home-card-gradient: $grad-Miyazakisky; // Tooltip colors @@ -190,7 +191,7 @@ $tooltip-bg: $br-chartreuse; $tooltip-text: $g2-kevlar; // Support and feedback buttons -$feedback-btn-bg: $g3-castle; +$feedback-btn-bg: $grey25; // URL Modal colors $modal-field-bg: $g1-raven; diff --git a/assets/styles/themes/_theme-light.scss b/assets/styles/themes/_theme-light.scss index 3f9e651f18..06dfe44974 100644 --- a/assets/styles/themes/_theme-light.scss +++ b/assets/styles/themes/_theme-light.scss @@ -14,8 +14,8 @@ // General Styles // -------------------------------------------------- -$body-bg: $g18-cloud !default; -$radius: 3px !default; +$body-bg: #f3f4fb !default; +$radius: 2px !default; // TopNav Colors $topnav-link: $g8-storm !default; @@ -26,7 +26,7 @@ $theme-switch-dark: inline-block !default; // Search $sidebar-search-bg: $g20-white !default; -$sidebar-search-shadow: $g14-chromium !default; +$sidebar-search-shadow: #cfd1e5 !default; $sidebar-search-highlight: $b-pool !default; $sidebar-search-text: $g8-storm !default; @@ -54,7 +54,7 @@ $article-text: $g6-smoke !default; $article-bold: $g6-smoke !default; $article-link: $b-pool !default; $article-link-hover: $br-magenta !default; -$article-shadow: $g14-chromium !default; +$article-shadow: #cfd1e5 !default; $article-hr: $g15-platinum !default; // Article Code @@ -75,7 +75,7 @@ $article-code-scrollbar: $cp-periwinkle !default; // Article Tables $article-table-header: $grad-Miyazakisky !default; -$article-table-row-alt: #F6F7F8 !default; +$article-table-row-alt: #f6f8ff !default; $article-table-scrollbar: $g14-chromium !default; // Article Notes & Warnings @@ -101,6 +101,7 @@ $article-note-code-accent7: #e90 !default; $article-note-code-scrollbar: #87DABE !default; $article-warn-base: $r-dreamsicle !default; +$article-warn-bg: rgba($r-dreamsicle, .08) !default; $article-warn-heading: $r-fire !default; $article-warn-text: $r-curacao !default; $article-warn-link: $r-curacao !default; @@ -110,7 +111,7 @@ $article-warn-table-row-alt: #ffe6df !default; $article-warn-table-scrollbar: #FFB1B1 !default; $article-warn-shadow: #b98a7d !default; $article-warn-code: #d0154e !default; -$article-warn-code-bg: #FFDDDC !default; +$article-warn-code-bg: #fde6e5 !default; $article-warn-code-accent1: #fd99b8 !default; $article-warn-code-accent2: #357ae8 !default; $article-warn-code-accent3: #6c59cc !default; @@ -147,7 +148,7 @@ $article-enterprise-link-hover: $b-pool !default; // Article Tabs for tabbed content $article-tab-text: $g8-storm !default; -$article-tab-bg: $g18-cloud !default; +$article-tab-bg: $grey95 !default; $article-tab-active-text: $g20-white !default; $article-tab-active-bg: $b-pool !default; $article-tab-code-text: $cp-marguerite !default; diff --git a/assets/styles/tools/_color-palette.scss b/assets/styles/tools/_color-palette.scss index 78cf16c6ac..15f437560f 100644 --- a/assets/styles/tools/_color-palette.scss +++ b/assets/styles/tools/_color-palette.scss @@ -148,3 +148,21 @@ $grad-PurpleRain: $p-void, $cp-marguerite; // Transparent gradients $grad-whiteFade: rgba($g20-white, .75), rgba($g20-white, 0); + +////////////////////////////// CLOCKFACE 3 COLORS ////////////////////////////// + +$grey5: #07070E; +$grey10: #14141F; +$grey15: #1A1A2A; +$grey20: #262738; +$grey25: #333346; +$grey35: #4D4D60; +$grey45: #68687B; +$grey55: #828294; +$grey65: #9E9EAD; +$grey75: #B9B9C5; +$grey85: #D5D5DD; +$grey95: #F1F1F3; +$white: #FFFFFF; + +$grad-cool-grey-abyss: $grey10, $grey15; \ No newline at end of file diff --git a/assets/styles/tools/_icomoon.scss b/assets/styles/tools/_icomoon-v2.scss similarity index 91% rename from assets/styles/tools/_icomoon.scss rename to assets/styles/tools/_icomoon-v2.scss index c871239ffa..d81cd1c1ee 100644 --- a/assets/styles/tools/_icomoon.scss +++ b/assets/styles/tools/_icomoon-v2.scss @@ -1,10 +1,10 @@ @font-face { - font-family: 'icomoon'; - src: url('fonts/icomoon.eot?itn2ph'); - src: url('fonts/icomoon.eot?itn2ph#iefix') format('embedded-opentype'), - url('fonts/icomoon.ttf?itn2ph') format('truetype'), - url('fonts/icomoon.woff?itn2ph') format('woff'), - url('fonts/icomoon.svg?itn2ph#icomoon') format('svg'); + font-family: 'icomoon-v2'; + src: url('fonts/icomoon-v2.eot?itn2ph'); + src: url('fonts/icomoon-v2.eot?itn2ph#iefix') format('embedded-opentype'), + url('fonts/icomoon-v2.ttf?itn2ph') format('truetype'), + url('fonts/icomoon-v2.woff?itn2ph') format('woff'), + url('fonts/icomoon-v2.svg?itn2ph#icomoon-v2') format('svg'); font-weight: normal; font-style: normal; font-display: block; @@ -12,7 +12,7 @@ [class^="icon-"], [class*=" icon-"] { /* use !important to prevent issues with browser extensions that change fonts */ - font-family: 'icomoon' !important; + font-family: 'icomoon-v2' !important; speak: never; font-style: normal; font-weight: normal; diff --git a/assets/styles/tools/_icon.scss b/assets/styles/tools/_icon.scss new file mode 100644 index 0000000000..a8a1c883af --- /dev/null +++ b/assets/styles/tools/_icon.scss @@ -0,0 +1,525 @@ +/* + Icon Font + ----------------------------------------------------------------------------- + Created using a tool called IcoMoon + See more at http://icomoon.io +*/ + +@font-face { + font-family: 'icomoon'; + src: url('fonts/icomoon.eot') format('embedded-opentype'); + src: url('fonts/icomoon.eot') format('embedded-opentype'), + url('fonts/icomoon.woff2') format('woff2'), + url('fonts/icomoon.ttf') format('truetype'), + url('fonts/icomoon.woff') format('woff'), + url('fonts/icomoon.svg') format('svg'); + font-weight: normal; + font-style: normal; +} + +.cf-icon { + font-family: 'icomoon' !important; + font-style: normal; + font-weight: normal; + font-variant: normal; + text-transform: none; + line-height: 1; + + // Better Font Rendering + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; + + &.add-cell-new:before { + content: '\e976'; + } + &.alert-triangle-new:before { + content: '\e977'; + } + &.annotate-new:before { + content: '\e978'; + } + &.arrow-down-new:before { + content: '\e979'; + } + &.arrow-left-new:before { + content: '\e97a'; + } + &.arrow-right-new:before { + content: '\e97b'; + } + &.arrow-up-new:before { + content: '\e97c'; + } + &.bar-chart-new:before { + content: '\e97d'; + } + &.build-outline-new:before { + content: '\e97e'; + } + &.caret-down-new:before { + content: '\e97f'; + } + &.caret-left-new:before { + content: '\e980'; + } + &.caret-right-new:before { + content: '\e981'; + } + &.caret-up-new:before { + content: '\e982'; + } + &.checkmark-new:before { + content: '\e983'; + } + &.clipboard-new:before { + content: '\e984'; + } + &.clock-new:before { + content: '\e985'; + } + &.cog-outline-new:before { + content: '\e986'; + } + &.cog-solid-new:before { + content: '\e987'; + } + &.crown-solid-new:before { + content: '\e988'; + } + &.dark-mode-new:before { + content: '\e989'; + } + &.download-new:before { + content: '\e98a'; + } + &.duplicate-new:before { + content: '\e98b'; + } + &.expand-new:before { + content: '\e98c'; + } + &.export-new:before { + content: '\e98d'; + } + &.eye-open-new:before { + content: '\e98e'; + } + &.graph-line-new:before { + content: '\e98f'; + } + &.handle-new:before { + content: '\e990'; + } + &.home-outline-new:before { + content: '\e991'; + } + &.info-new:before { + content: '\e992'; + } + &.ingest-new:before { + content: '\e993'; + } + &.light-mode-new:before { + content: '\e994'; + } + &.lock-outline-new:before { + content: '\e995'; + } + &.log-out-new:before { + content: '\e996'; + } + &.pin-new:before { + content: '\e997'; + } + &.plus-new:before { + content: '\e998'; + } + &.question-mark-new:before { + content: '\e999'; + } + &.refresh-new:before { + content: '\e99a'; + } + &.remove-new:before { + content: '\e99b'; + } + &.search-new:before { + content: '\e99c'; + } + &.sidebar-close-new:before { + content: '\e99d'; + } + &.sidebar-open-new:before { + content: '\e99e'; + } + &.stop-new:before { + content: '\e99f'; + } + &.switch-new:before { + content: '\e9a0'; + } + &.text-new:before { + content: '\e9a1'; + } + &.trash-new:before { + content: '\e9a2'; + } + &.user-outline-new:before { + content: '\e9a3'; + } + &.more:before { + content: '\e974'; + } + &.drag-to-expand-white:before { + content: '\e901'; + color: #fff; + } + &.drag-to-expand:before { + content: '\e902'; + } + &.shield-solid:before { + content: '\e903'; + } + &.lock:before { + content: '\e900'; + } + &.heart-solid:before { + content: '\e96f'; + } + &.bucket-outline:before { + content: '\e961'; + } + &.chat:before { + content: '\e933'; + } + &.currency-eur:before { + content: '\e968'; + } + &.currency-gbp:before { + content: '\e969'; + } + &.currency-usd:before { + content: '\e96a'; + } + &.moon:before { + content: '\e95c'; + } + &.share-solid:before { + content: '\e96e'; + } + &.shield:before { + content: '\e96b'; + } + &.sun:before { + content: '\e95d'; + } + &.upgrade:before { + content: '\e95f'; + } + &.merge:before { + content: '\e975'; + } + &.add-cell:before { + content: '\e925'; + } + &.alert-triangle:before { + content: '\e926'; + } + &.alerts:before { + content: '\e921'; + } + &.annotate:before { + content: '\e953'; + } + &.annotate-plus:before { + content: '\e952'; + } + &.authzero:before { + content: '\e951'; + } + &.bar-chart:before { + content: '\e913'; + } + &.bell:before { + content: '\e934'; + } + &.bell-solid:before { + content: '\e937'; + } + &.brush:before { + content: '\e93d'; + } + &.capacitor2:before { + content: '\e923'; + } + &.caret-down:before { + content: '\e904'; + } + &.caret-left:before { + content: '\e905'; + } + &.caret-right:before { + content: '\e906'; + } + &.caret-up:before { + content: '\e907'; + } + &.checkmark:before { + content: '\e918'; + } + &.circle:before { + content: '\e940'; + } + &.circle-thick:before { + content: '\e90e'; + } + &.clock:before { + content: '\e920'; + } + &.cog-outline:before { + content: '\e91c'; + } + &.cog-thick:before { + content: '\e90c'; + } + &.collapse:before { + content: '\e91b'; + } + &.crown-outline:before { + content: '\e908'; + } + &.crown2:before { + content: '\e94b'; + } + &.cube:before { + content: '\e90b'; + } + &.cubo:before { + content: '\e95e'; + } + &.cubo-uniform:before { + content: '\e93c'; + } + &.dash-f:before { + content: '\e927'; + } + &.dash-h:before { + content: '\e929'; + } + &.dash-j:before { + content: '\e92b'; + } + &.disks:before { + content: '\e950'; + } + &.download:before { + content: '\e91d'; + } + &.duplicate:before { + content: '\e917'; + } + &.erlenmeyer:before { + content: '\e958'; + } + &.expand-a:before { + content: '\e944'; + } + &.expand-b:before { + content: '\e942'; + } + &.export:before { + content: '\e90f'; + } + &.eye:before { + content: '\e91f'; + } + &.eye-closed:before { + content: '\e956'; + } + &.eye-open:before { + content: '\e957'; + } + &.fn:before { + content: '\e960'; + } + &.github:before { + content: '\e928'; + } + &.google:before { + content: '\e92a'; + } + &.group:before { + content: '\e909'; + } + &.heroku:before { + content: '\e947'; + } + &.heroku-simple:before { + content: '\e948'; + } + &.import:before { + content: '\e910'; + } + &.link:before { + content: '\e92e'; + } + &.maximize:before { + content: '\e955'; + } + &.minimize:before { + content: '\e954'; + } + &.nav-chat:before { + content: '\e941'; + } + &.oauth:before { + content: '\e94f'; + } + &.octagon:before { + content: '\e92d'; + } + &.okta:before { + content: '\e912'; + } + &.pause:before { + content: '\e94a'; + } + &.pencil:before { + content: '\e92f'; + } + &.play:before { + content: '\e914'; + } + &.plus:before { + content: '\e90a'; + } + &.plus-skinny:before { + content: '\e922'; + } + &.polaroid:before { + content: '\e95b'; + } + &.pulse-c:before { + content: '\e936'; + } + &.redo:before { + content: '\e959'; + } + &.refresh:before { + content: '\e949'; + } + &.remove:before { + content: '\e90d'; + } + &.search:before { + content: '\e916'; + } + &.server2:before { + content: '\e94c'; + } + &.shuffle:before { + content: '\e94e'; + } + &.square:before { + content: '\e93e'; + } + &.square-check:before { + content: '\e943'; + } + &.star:before { + content: '\e930'; + } + &.stop:before { + content: '\e931'; + } + &.text-block:before { + content: '\e911'; + } + &.trash:before { + content: '\e915'; + } + &.triangle:before { + content: '\e92c'; + } + &.undo:before { + content: '\e95a'; + } + &.user:before { + content: '\e919'; + } + &.user-add:before { + content: '\e91e'; + } + &.user-outline:before { + content: '\e932'; + } + &.user-remove:before { + content: '\e939'; + } + &.users-trio:before { + content: '\e945'; + } + &.wand:before { + content: '\e94d'; + } + &.wood:before { + content: '\e970'; + } + &.wrench:before { + content: '\e971'; + } + &.zap:before { + content: '\e973'; + } + &.bell-ringing:before { + content: '\e935'; + } + &.calendar:before { + content: '\e938'; + } + &.cloud:before { + content: '\e93f'; + } + &.cubo-nav:before { + content: '\e91a'; + } + &.dashboards:before { + content: '\e93a'; + } + &.disks-nav:before { + content: '\e946'; + } + &.graphline-2:before { + content: '\e924'; + } + &.users-duo:before { + content: '\e93b'; + } + &.wrench-nav:before { + content: '\e972'; + } + &.book:before { + content: '\e966'; + } + &.book-code:before { + content: '\e967'; + } + &.book-pencil:before { + content: '\e965'; + } + &.bucket-solid:before { + content: '\e962'; + } + &.funnel-outline:before { + content: '\e963'; + } + &.funnel-solid:before { + content: '\e964'; + } + &.layers:before { + content: '\e96c'; + } + &.share:before { + content: '\e96d'; + } +} diff --git a/assets/styles/tools/_tooltips.scss b/assets/styles/tools/_tooltips.scss index 72673ff6a9..ff7e691f0e 100644 --- a/assets/styles/tools/_tooltips.scss +++ b/assets/styles/tools/_tooltips.scss @@ -4,9 +4,6 @@ $medium: 500; $bold: 700; -// Border radius -$radius: 3px; - ////////////////////////////////// Tool Tips ////////////////////////////////// .tooltip { diff --git a/config.staging.toml b/config.staging.toml index 02aee5b554..dca5748bd6 100644 --- a/config.staging.toml +++ b/config.staging.toml @@ -25,8 +25,10 @@ hrefTargetBlank = true smartDashes = false [taxonomies] + "influxdb/v2.1/tag" = "influxdb/v2.1/tags" "influxdb/v2.0/tag" = "influxdb/v2.0/tags" "influxdb/cloud/tag" = "influxdb/cloud/tags" + "flux/v0.x/tag" = "flux/v0.x/tags" [markup] [markup.goldmark] diff --git a/config.toml b/config.toml index 954358d99d..066aa3f497 100644 --- a/config.toml +++ b/config.toml @@ -21,6 +21,7 @@ hrefTargetBlank = true smartDashes = false [taxonomies] + "influxdb/v2.1/tag" = "influxdb/v2.1/tags" "influxdb/v2.0/tag" = "influxdb/v2.0/tags" "influxdb/cloud/tag" = "influxdb/cloud/tags" "flux/v0.x/tag" = "flux/v0.x/tags" diff --git a/content/chronograf/v1.9/guides/advanced-kapacitor.md b/content/chronograf/v1.9/guides/advanced-kapacitor.md index 8e7854ed16..dfc723f798 100644 --- a/content/chronograf/v1.9/guides/advanced-kapacitor.md +++ b/content/chronograf/v1.9/guides/advanced-kapacitor.md @@ -33,7 +33,7 @@ of the default retention policy. Use the Chronograf **Admin page** to modify the retention policy in the `chronograf` database. In the Databases tab: -1. Click **{{< icon "crown" >}} InfluxDB Admin** in the left navigation bar. +1. Click **{{< icon "crown" "v2" >}} InfluxDB Admin** in the left navigation bar. 2. Hover over the retention policy list of the `chronograf` database and click **Edit** next to the retention policy to update. 3. Update the **Duration** of the retention policy. @@ -55,7 +55,7 @@ Chronograf lets you manage Kapacitor TICKscript tasks created in Kapacitor or in Chronograf when [creating a Chronograf alert rule](/chronograf/v1.9/guides/create-alert-rules/). To manage Kapacitor TICKscript tasks in Chronograf, click -**{{< icon "alert">}} Alerts** in the left navigation bar. +**{{< icon "alert" "v2">}} Alerts** in the left navigation bar. On this page, you can: - View Kapacitor TICKscript tasks. @@ -70,7 +70,7 @@ On this page, you can: Chronograf lets you view and manage [Kapacitor Flux tasks](/{{< latest "kapacitor" >}}/working/flux/). To manage Kapacitor Flux tasks in Chronograf, click -**{{< icon "alert">}} Alerts** in the left navigation bar. +**{{< icon "alert" "v2">}} Alerts** in the left navigation bar. On this page, you can: - View Kapacitor Flux tasks. diff --git a/content/chronograf/v1.9/guides/analyzing-logs.md b/content/chronograf/v1.9/guides/analyzing-logs.md index 8af2e24fb3..a102b59ca2 100644 --- a/content/chronograf/v1.9/guides/analyzing-logs.md +++ b/content/chronograf/v1.9/guides/analyzing-logs.md @@ -94,10 +94,10 @@ To copy the complete, un-truncated log message, select the message cell and clic ## Show or hide the log status histogram The Chronograf Log Viewer displays a histogram of log status. -**To hide the log status histogram**, click the **{{< icon "hide" >}} icon** in +**To hide the log status histogram**, click the **{{< icon "hide" "v2" >}} icon** in the top right corner of the histogram. -**To show the log status histogram**, click the **{{< icon "bar-chart" >}} icon** +**To show the log status histogram**, click the **{{< icon "bar-chart" "v2" >}} icon** in the top right corner of the log output. ## Logs in dashboards diff --git a/content/chronograf/v1.9/guides/configuring-alert-endpoints.md b/content/chronograf/v1.9/guides/configuring-alert-endpoints.md index e12cd0ce20..9988092c58 100644 --- a/content/chronograf/v1.9/guides/configuring-alert-endpoints.md +++ b/content/chronograf/v1.9/guides/configuring-alert-endpoints.md @@ -253,7 +253,7 @@ To enable a new "Generic API" service using TICKscript, see [AlertNode (Kapacito 1. In the **Configure Alert Endpoints** of the **Configure Kapacitor Connection** page, click the **Slack** tab. -2. Click **{{< icon "plus" >}} Add Another Config**. +2. Click **{{< icon "plus" "v2" >}} Add Another Config**. 3. Complete steps 2-4 [above](#slack). ### SMTP diff --git a/content/chronograf/v1.9/guides/create-a-dashboard.md b/content/chronograf/v1.9/guides/create-a-dashboard.md index ffe58fa038..5afaa5d834 100644 --- a/content/chronograf/v1.9/guides/create-a-dashboard.md +++ b/content/chronograf/v1.9/guides/create-a-dashboard.md @@ -32,14 +32,14 @@ For more information, see [Configuring Chronograf](/chronograf/v1.9/administrati ## Build a dashboard 1. #### Create a new dashboard - Click **Dashboards** in the navigation bar and then click the **{{< icon "plus" >}} Create Dashboard** button. + Click **Dashboards** in the navigation bar and then click the **{{< icon "plus" "v2" >}} Create Dashboard** button. A new dashboard is created and ready to begin adding cells. 2. #### Name your dashboard Click **Name This Dashboard** and type a new name. For example, "ChronoDash". 3. #### Enter cell editor mode - In the first cell, titled "Untitled Cell", click **{{< icon "plus" >}} Add Data** + In the first cell, titled "Untitled Cell", click **{{< icon "plus" "v2" >}} Add Data** to open the cell editor mode. {{< img-hd src="/img/chronograf/1-9-dashboard-cell-add-data.png" alt="Add data to a Chronograf cell" />}} @@ -155,7 +155,7 @@ Select from a variety of dashboard templates to import and customize based on wh ### Full screen mode -View your dashboard in full screen mode by clicking on the full screen icon (**{{< icon "fullscreen" >}}**) in the top right corner of your dashboard. +View your dashboard in full screen mode by clicking on the full screen icon (**{{< icon "fullscreen" "v2" >}}**) in the top right corner of your dashboard. To exit full screen mode, press the Esc key. ### Template variables diff --git a/content/chronograf/v1.9/guides/write-to-influxdb.md b/content/chronograf/v1.9/guides/write-to-influxdb.md index 15f1e18484..c677e12dfe 100644 --- a/content/chronograf/v1.9/guides/write-to-influxdb.md +++ b/content/chronograf/v1.9/guides/write-to-influxdb.md @@ -19,7 +19,7 @@ Choose from the following methods: ## Upload line protocol through the Chronograf UI -1. Select **{{< icon "data-explorer" >}} Explore** in the left navigation bar. +1. Select **{{< icon "data-explorer" "v2" >}} Explore** in the left navigation bar. 2. Click **Write Data** in the top right corner of the Data Explorer. {{< img-hd src="/img/chronograf/1-9-write-data.png" alt="Write data to InfluxDB with Chronograf" />}} @@ -53,7 +53,7 @@ To write data back to InfluxDB with an InfluxQL query, include the [`INTO` clause](/{{< latest "influxdb" "v1" >}}/query_language/explore-data/#the-into-clause) in your query: -1. Select **{{< icon "data-explorer" >}} Explore** in the left navigation bar. +1. Select **{{< icon "data-explorer" "v2" >}} Explore** in the left navigation bar. 2. Select **InfluxQL** as your data source type. 3. Write an InfluxQL query that includes the `INTO` clause. Specify the database, retention policy, and measurement to write to. For example: @@ -80,7 +80,7 @@ To write data back to InfluxDB with an InfluxQL query, include the [`INTO` clause](/{{< latest "influxdb" "v1" >}}/query_language/explore-data/#the-into-clause) in your query: -1. Select **{{< icon "data-explorer" >}} Explore** in the left navigation bar. +1. Select **{{< icon "data-explorer" "v2" >}} Explore** in the left navigation bar. 2. Select **Flux** as your data source type. {{% note %}} diff --git a/content/enterprise_influxdb/v1.9/administration/monitor/monitor-with-cloud.md b/content/enterprise_influxdb/v1.9/administration/monitor/monitor-with-cloud.md index 875239a09e..9aa2aecdba 100644 --- a/content/enterprise_influxdb/v1.9/administration/monitor/monitor-with-cloud.md +++ b/content/enterprise_influxdb/v1.9/administration/monitor/monitor-with-cloud.md @@ -145,7 +145,7 @@ To alert when data stops flowing from InfluxDB OSS instances to your InfluxDB Cl {{< nav-icon "alerts" >}} 2. Choose a InfluxDB OSS field or create a new OSS field for your deadman alert: - 1. Click **{{< icon "plus" >}} Create** and select **Deadman Check** in the dropown menu. + 1. Click **{{< icon "plus" "v2" >}} Create** and select **Deadman Check** in the dropown menu. 2. Define your query with at least one field. 3. Click **Submit** and **Configure Check**. When metrics stop reporting, you'll receive an alert. @@ -164,7 +164,7 @@ InfluxDB Cloud supports different endpoints: Slack, PagerDuty, and HTTP. Slack i #### Send a notification to Slack 1. Create a [Slack Webhooks](https://api.slack.com/messaging/webhooks). -2. Go to **Alerts > Notification Endpoint** and click **{{< icon "plus" >}} Create**, and enter a name and description for your Slack endpoint. +2. Go to **Alerts > Notification Endpoint** and click **{{< icon "plus" "v2" >}} Create**, and enter a name and description for your Slack endpoint. 3. Enter your Slack Webhook under **Incoming Webhook URL** and click **Create Notification Endpoint**. #### Send a notification to PagerDuty or HTTP @@ -175,7 +175,7 @@ Send a notification to PagerDuty or HTTP endpoints (other webhooks) by [upgradin [Create a notification rule](/influxdb/cloud/monitor-alert/notification-rules/create/) to set rules for when to send a deadman alert message to your notification endpoint. -1. Go to **Alerts > Notification Rules** and click **{{< icon "plus" >}} Create**. +1. Go to **Alerts > Notification Rules** and click **{{< icon "plus" "v2" >}} Create**. 2. Fill out the **About** and **Conditions** section then click **Create Notification Rule**. ## Monitor with InfluxDB Insights and Aware diff --git a/content/enterprise_influxdb/v1.9/administration/monitor/monitor-with-oss.md b/content/enterprise_influxdb/v1.9/administration/monitor/monitor-with-oss.md index 271bc9c1ff..add587b444 100644 --- a/content/enterprise_influxdb/v1.9/administration/monitor/monitor-with-oss.md +++ b/content/enterprise_influxdb/v1.9/administration/monitor/monitor-with-oss.md @@ -145,7 +145,7 @@ To alert when data stops flowing from InfluxDB OSS instances to your InfluxDB OS {{< nav-icon "alerts" >}} 2. Choose a InfluxDB OSS field or create a new OSS field for your deadman alert: - 1. Click **{{< icon "plus" >}} Create** and select **Deadman Check** in the dropown menu. + 1. Click **{{< icon "plus" "v2" >}} Create** and select **Deadman Check** in the dropown menu. 2. Define your query with at least one field. 3. Click **Submit** and **Configure Check**. When metrics stop reporting, you'll receive an alert. @@ -164,7 +164,7 @@ InfluxData supports different endpoints: Slack, PagerDuty, and HTTP. Slack is fr #### Send a notification to Slack 1. Create a [Slack Webhooks](https://api.slack.com/messaging/webhooks). -2. Go to **Alerts > Notification Endpoint** and click **{{< icon "plus" >}} Create**, and enter a name and description for your Slack endpoint. +2. Go to **Alerts > Notification Endpoint** and click **{{< icon "plus" "v2" >}} Create**, and enter a name and description for your Slack endpoint. 3. Enter your Slack Webhook under **Incoming Webhook URL** and click **Create Notification Endpoint**. #### Send a notification to PagerDuty or HTTP @@ -175,5 +175,5 @@ Send a notification to PagerDuty or HTTP endpoints (other webhooks) by [upgradin [Create a notification rule](/influxdb/v2.0/monitor-alert/notification-rules/create/) to set rules for when to send a deadman alert message to your notification endpoint. -1. Go to **Alerts > Notification Rules** and click **{{< icon "plus" >}} Create**. +1. Go to **Alerts > Notification Rules** and click **{{< icon "plus" "v2" >}} Create**. 2. Fill out the **About** and **Conditions** section then click **Create Notification Rule**. diff --git a/content/enterprise_influxdb/v1.9/flux/optimize-queries.md b/content/enterprise_influxdb/v1.9/flux/optimize-queries.md index f4c25504a9..be44bb903d 100644 --- a/content/enterprise_influxdb/v1.9/flux/optimize-queries.md +++ b/content/enterprise_influxdb/v1.9/flux/optimize-queries.md @@ -29,29 +29,29 @@ The following pushdowns are supported in InfluxDB Enterprise 1.9+. | Functions | Supported | | :----------------------------- | :------------------: | -| **count()** | {{< icon "check" >}} | -| **drop()** | {{< icon "check" >}} | -| **duplicate()** | {{< icon "check" >}} | -| **filter()** {{% req " \*" %}} | {{< icon "check" >}} | -| **fill()** | {{< icon "check" >}} | -| **first()** | {{< icon "check" >}} | -| **group()** | {{< icon "check" >}} | -| **keep()** | {{< icon "check" >}} | -| **last()** | {{< icon "check" >}} | -| **max()** | {{< icon "check" >}} | -| **mean()** | {{< icon "check" >}} | -| **min()** | {{< icon "check" >}} | -| **range()** | {{< icon "check" >}} | -| **rename()** | {{< icon "check" >}} | -| **sum()** | {{< icon "check" >}} | -| **window()** | {{< icon "check" >}} | +| **count()** | {{< icon "check" "v2" >}} | +| **drop()** | {{< icon "check" "v2" >}} | +| **duplicate()** | {{< icon "check" "v2" >}} | +| **filter()** {{% req " \*" %}} | {{< icon "check" "v2" >}} | +| **fill()** | {{< icon "check" "v2" >}} | +| **first()** | {{< icon "check" "v2" >}} | +| **group()** | {{< icon "check" "v2" >}} | +| **keep()** | {{< icon "check" "v2" >}} | +| **last()** | {{< icon "check" "v2" >}} | +| **max()** | {{< icon "check" "v2" >}} | +| **mean()** | {{< icon "check" "v2" >}} | +| **min()** | {{< icon "check" "v2" >}} | +| **range()** | {{< icon "check" "v2" >}} | +| **rename()** | {{< icon "check" "v2" >}} | +| **sum()** | {{< icon "check" "v2" >}} | +| **window()** | {{< icon "check" "v2" >}} | | _Function combinations_ | | -| **window()** \|> **count()** | {{< icon "check" >}} | -| **window()** \|> **first()** | {{< icon "check" >}} | -| **window()** \|> **last()** | {{< icon "check" >}} | -| **window()** \|> **max()** | {{< icon "check" >}} | -| **window()** \|> **min()** | {{< icon "check" >}} | -| **window()** \|> **sum()** | {{< icon "check" >}} | +| **window()** \|> **count()** | {{< icon "check" "v2" >}} | +| **window()** \|> **first()** | {{< icon "check" "v2" >}} | +| **window()** \|> **last()** | {{< icon "check" "v2" >}} | +| **window()** \|> **max()** | {{< icon "check" "v2" >}} | +| **window()** \|> **min()** | {{< icon "check" "v2" >}} | +| **window()** \|> **sum()** | {{< icon "check" "v2" >}} | {{% caption %}} {{< req "\*" >}} **filter()** only pushes down when all parameter values are static. diff --git a/content/example.md b/content/example.md index c770a3540b..49c1c960bd 100644 --- a/content/example.md +++ b/content/example.md @@ -10,7 +10,7 @@ related: products: [cloud, oss, enterprise] --- -This is a paragraph. Lorem ipsum dolor ({{< icon "trash" >}}) sit amet, consectetur adipiscing elit. Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, vel tempor odio dolor blandit justo. +This is a paragraph. Lorem ipsum dolor ({{< icon "trash" "v2" >}}) sit amet, consectetur adipiscing elit. Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, vel tempor odio dolor blandit justo. [Ref link][foo] @@ -18,10 +18,83 @@ This is a paragraph. Lorem ipsum dolor ({{< icon "trash" >}}) sit amet, consecte This is **bold** text. This is _italic_ text. This is _**bold and italic**_. +{{< nav-icon "account" "v2" >}} +{{< nav-icon "data" "v2" >}} +{{< nav-icon "explore" "v2" >}} +{{< nav-icon "org" "v2" >}} +{{< nav-icon "boards" "v2" >}} +{{< nav-icon "tasks" "v2" >}} +{{< nav-icon "alerts" "v2" >}} +{{< nav-icon "settings" "v2" >}} +{{< nav-icon "notebooks" "v2" >}} + +{{< icon "add-cell" "v2" >}} add-cell +{{< icon "add-label" "v2" >}} add-label +{{< icon "alert" "v2" >}} alert +{{< icon "calendar" "v2" >}} calendar +{{< icon "chat" "v2" >}} chat +{{< icon "checkmark" "v2" >}} checkmark +{{< icon "clone" "v2" >}} clone +{{< icon "cloud" "v2" >}} cloud +{{< icon "cog" "v2" >}} cog +{{< icon "config" "v2" >}} config +{{< icon "copy" "v2" >}} copy +{{< icon "crown" "v2" >}} crown +{{< icon "dashboard" "v2" >}} dashboard +{{< icon "dashboards" "v2" >}} dashboards +{{< icon "data-explorer" "v2" >}} data-explorer +{{< icon "delete" "v2" >}} delete +{{< icon "download" "v2" >}} download +{{< icon "duplicate" "v2" >}} duplicate +{{< icon "edit" "v2" >}} edit +{{< icon "expand" "v2" >}} expand +{{< icon "export" "v2" >}} export +{{< icon "eye" "v2" >}} eye +{{< icon "eye-closed" "v2" >}} eye-closed +{{< icon "eye-open" "v2" >}} eye-open +{{< icon "feedback" "v2" >}} feedback +{{< icon "fullscreen" "v2" >}} fullscreen +{{< icon "gear" "v2" >}} gear +{{< icon "graph" "v2" >}} graph +{{< icon "hide" "v2" >}} hide +{{< icon "influx" "v2" >}} influx +{{< icon "influx-icon" "v2" >}} influx-icon +{{< icon "nav-admin" "v2" >}} nav-admin +{{< icon "nav-config" "v2" >}} nav-config +{{< icon "nav-configuration" "v2" >}} nav-configuration +{{< icon "nav-dashboards" "v2" >}} nav-dashboards +{{< icon "nav-data-explorer" "v2" >}} nav-data-explorer +{{< icon "nav-organizations" "v2" >}} nav-organizations +{{< icon "nav-orgs" "v2" >}} nav-orgs +{{< icon "nav-tasks" "v2" >}} nav-tasks +{{< icon "note" "v2" >}} note +{{< icon "notebook" "v2" >}} notebook +{{< icon "notebooks" "v2" >}} notebooks +{{< icon "org" "v2" >}} org +{{< icon "orgs" "v2" >}} orgs +{{< icon "pause" "v2" >}} pause +{{< icon "pencil" "v2" >}} pencil +{{< icon "play" "v2" >}} play +{{< icon "plus" "v2" >}} plus +{{< icon "refresh" "v2" >}} refresh +{{< icon "remove" "v2" >}} remove +{{< icon "replay" "v2" >}} replay +{{< icon "save-as" "v2" >}} save-as +{{< icon "search" "v2" >}} search +{{< icon "settings" "v2" >}} settings +{{< icon "tasks" "v2" >}} tasks +{{< icon "toggle" "v2" >}} toggle +{{< icon "trash" "v2" >}} trash +{{< icon "trashcan" "v2" >}} trashcan +{{< icon "triangle" "v2" >}} triangle +{{< icon "view" "v2" >}} view +{{< icon "wrench" "v2" >}} wrench +{{< icon "x" "v2" >}} x + +### Clockface 3.x icons {{< nav-icon "account" >}} {{< nav-icon "data" >}} {{< nav-icon "explore" >}} -{{< nav-icon "org" >}} {{< nav-icon "boards" >}} {{< nav-icon "tasks" >}} {{< nav-icon "alerts" >}} @@ -31,9 +104,13 @@ This is **bold** text. This is _italic_ text. This is _**bold and italic**_. {{< icon "add-cell" >}} add-cell {{< icon "add-label" >}} add-label {{< icon "alert" >}} alert +{{< icon "annotate" >}} annotate +{{< icon "bar-chart" >}} bar-chart +{{< icon "bar-graph" >}} bar-graph {{< icon "calendar" >}} calendar {{< icon "chat" >}} chat {{< icon "checkmark" >}} checkmark +{{< icon "clock" >}} clock {{< icon "clone" >}} clone {{< icon "cloud" >}} cloud {{< icon "cog" >}} cog @@ -56,9 +133,12 @@ This is **bold** text. This is _italic_ text. This is _**bold and italic**_. {{< icon "fullscreen" >}} fullscreen {{< icon "gear" >}} gear {{< icon "graph" >}} graph +{{< icon "handle" >}} handle {{< icon "hide" >}} hide {{< icon "influx" >}} influx {{< icon "influx-icon" >}} influx-icon +{{< icon "move" >}} move +{{< icon "move-cell" >}} move-cell {{< icon "nav-admin" >}} nav-admin {{< icon "nav-config" >}} nav-config {{< icon "nav-configuration" >}} nav-configuration @@ -74,6 +154,7 @@ This is **bold** text. This is _italic_ text. This is _**bold and italic**_. {{< icon "orgs" >}} orgs {{< icon "pause" >}} pause {{< icon "pencil" >}} pencil +{{< icon "pin" >}} pin {{< icon "play" >}} play {{< icon "plus" >}} plus {{< icon "refresh" >}} refresh @@ -89,7 +170,7 @@ This is **bold** text. This is _italic_ text. This is _**bold and italic**_. {{< icon "triangle" >}} triangle {{< icon "view" >}} view {{< icon "wrench" >}} wrench -{{< icon "x" >}} x +{{< icon "x" >}} x ## h2 This is a header2 This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, vel tempor odio dolor blandit justo. @@ -771,3 +852,29 @@ This is truncated content. This is truncated content. This is truncated content. {{% /truncate %}} + +{{< tabs-wrapper >}} +{{% tabs "small" %}} +[Small tab 2.1](#) +[Small tab 2.2](#) +[Small tab 2.3](#) +[Small tab 2.4](#) +{{% /tabs %}} + +{{% tab-content %}} +This is small tab 2.1 content. +{{% /tab-content %}} + +{{% tab-content %}} +This is small tab 2.2 content. +{{% /tab-content %}} + +{{% tab-content %}} +This is small tab 2.3 content. +{{% /tab-content %}} + +{{% tab-content %}} +This is small tab 2.4 content. +{{% /tab-content %}} + +{{< /tabs-wrapper >}} diff --git a/content/flux/v0.x/stdlib/universe/tripleema.md b/content/flux/v0.x/stdlib/universe/tripleema.md index 49e8dafa0a..af2cc71ad3 100644 --- a/content/flux/v0.x/stdlib/universe/tripleema.md +++ b/content/flux/v0.x/stdlib/universe/tripleema.md @@ -28,7 +28,7 @@ The `tripleEMA()` function calculates the exponential moving average of values i the `_value` column grouped into `n` number of points, giving more weight to recent data with less lag than [`exponentialMovingAverage()`](/flux/v0.x/stdlib/universe/exponentialmovingaverage/) -and [`doubleEMA()`](http://localhost:1313/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/doubleema/). +and [`doubleEMA()`](/flux/v0.x/stdlib/universe/doubleema/). ```js tripleEMA(n: 5) diff --git a/content/influxdb/cloud/get-started.md b/content/influxdb/cloud/get-started.md index f33cc409b4..04a5b3adeb 100644 --- a/content/influxdb/cloud/get-started.md +++ b/content/influxdb/cloud/get-started.md @@ -18,8 +18,10 @@ After you've [signed up for InfluxDB Cloud](/influxdb/cloud/sign-up/), you're re - Add [sample data](#add-sample-data). - [Use your own data](/influxdb/cloud/write-data/) to explore InfluxDB Cloud. 2. [Create a notebook](#create-a-notebook): - 1. Clicking **Books > Create Notebook** in the navigation menu on the left. + 1. Clicking **Notebooks** in the navigation menu on the left. + {{< nav-icon "books" >}} + 2. [Select metrics](#select-metrics) 3. [Visualize data](#visualize-data) 4. (Optional) [Process data](#process-data) @@ -30,11 +32,11 @@ After you've [signed up for InfluxDB Cloud](/influxdb/cloud/sign-up/), you're re This example uses InfluxDB Cloud's Website Monitoring demo data bucket. To add the demo data bucket: -1. Click **Data (Load Data)** > **Buckets** in the navigation menu on the left. +1. Click **Load Data** > **Buckets** in the navigation menu on the left. {{< nav-icon "data" >}} -2. Click **{{< icon "plus" >}} Add Demo Data**, and then select the **Website Monitoring** bucket. +2. Click **{{< icon "plus" >}} {{< caps >}}Add Demo Data{{< /caps >}}**, and then select the **Website Monitoring** bucket. 3. The Demo Data bucket appears in your list of buckets. ## Add sample data diff --git a/content/influxdb/cloud/notebooks/_index.md b/content/influxdb/cloud/notebooks/_index.md index 81f103921e..cff2444935 100644 --- a/content/influxdb/cloud/notebooks/_index.md +++ b/content/influxdb/cloud/notebooks/_index.md @@ -9,8 +9,4 @@ menu: weight: 6 --- -Notebooks are a way to build and annotate processes and data flows for time series data. Notebooks include cells and controls to transform the data in your bucket and other countless possibilities. - -To learn how to use notebooks, check out the following articles: - -{{< children >}} +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/notebooks/clean-data.md b/content/influxdb/cloud/notebooks/clean-data.md index 94a501947f..0123bc74fd 100644 --- a/content/influxdb/cloud/notebooks/clean-data.md +++ b/content/influxdb/cloud/notebooks/clean-data.md @@ -10,31 +10,4 @@ menu: parent: Notebooks --- -Learn how to create a notebook that normalizes data. Walk through the following example to create a notebook that does the following: - -- Inputs sample data from NOAA -- Normalizes sample data with a Flux script -- Outputs normalized data to a bucket - -## Requirements -- This example uses [NOAA water database data](/influxdb/v2.0/reference/sample-data/#noaa-water-sample-data). Note that using this data counts towards your total usage. -- Create a destination bucket to write normalized data to. For details, see [Create a bucket](/influxdb/cloud/organizations/buckets/create-bucket/). - -## Normalize data with a notebook -1. Create a new notebook (see [Create a notebook](/influxdb/cloud/notebooks/create-notebook/)). -2. Add a **Metric Selector** cell to select a bucket to query data from: - - In the **Choose a bucket** dropdown, select your NOAA bucket. - - Select the **h2o_temperature** field. - - Select the **mean** function from the aggregate selector in the upper-right. -3. Add a **Flux Transformation** cell with the following script to bring in data from the previous cell and normalize it: - ```sh - __PREVIOUS_RESULT__ - |> map(fn: (r) => ({ r with _value: float(v: r._value) / 10.0 })) - ``` -4. Add an **Output to Bucket** cell: - - Select the destination bucket for your normalized data. -5. Add a **Markdown** cell to add a note to your team about what this notebook does. For example, the cell might say, "This notebook makes `h20_temperature` easier to view alongside `water_level`." -5. Click **Preview** in the upper left to verify that your notebook runs and preview the output. -6. Run your notebook: - - Click **Run** to run the notebook and write to the output bucket a single time. - - To write continuously, click **Export as Task** in the upper right corner of the **Output to Bucket** cell. For details about working with tasks, see [Manage tasks](/influxdb/cloud/process-data/manage-tasks/). +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/notebooks/create-notebook.md b/content/influxdb/cloud/notebooks/create-notebook.md index 64206690b4..11dd21ca78 100644 --- a/content/influxdb/cloud/notebooks/create-notebook.md +++ b/content/influxdb/cloud/notebooks/create-notebook.md @@ -9,105 +9,4 @@ menu: name: Create a notebook parent: Notebooks --- -To learn how notebooks can be useful and to see an overview of different cell types available in notebooks, see [Overview of Notebooks](/influxdb/cloud/notebooks/overview/). - -1. In the navigation menu on the left, click **Notebooks**. - - {{< nav-icon "notebooks" >}} -2. Click **+Create Notebook**, and then enter a name for your notebook in the **Name this notebook** field. By default, the notebook name appears as `-notebook---`. -3. Do the following at the top of the page: - - Select your local time zone or UTC. - - Choose a time range for your data. -4. Consider which notebook cells to add to your notebook. You need to have one input cell for other cells to run properly. By default, each notebook includes **Metric Selector**, **Data Validation**, and **Visualization** cells. -5. Select your bucket in **Metric Selector** and then select the filters to narrow your data. -6. Do one of the following: - - To view results in your cells (for example, **Data Validation** and **Visualization**) *without writing data*, click **Preview** (or press **CTRL + Enter**). - - To view the results of each cell and write the results to the specified output bucket, click **Run**. -7. (Optional) Change your visualization settings with the dropdown menus and gear icon at the top of the **Visualization** cell. -8. (Optional) Click the **+** icon, and then add one or more of the following cell types to your notebook: - - - [Input](#add-an-input-cell): to pull information into your notebook - - [Transform](#add-a-transform-cell): to filter and apply changes to your data - - [Pass-through](#add-a-pass-through-cell): to visualize and add notes to your data - - [Output](#add-an-output-cell): to write data to a bucket, preview output before writing, or schedule an output task -9. (Optional) [Convert a cell into raw Flux script](#view-and-edit-flux-script-in-a-cell) to view and edit the code. - -### Add an input cell - -1. Select **Metric Builder** or **Query Builder** as your input, and then select the bucket to pull data from. -2. Select filters to narrow your data. -3. Select **Preview** (**CTRL + Enter**) or **Run** in the upper left dropdown menu. - -### Add a transform cell - -1. Select one of the following transform cell-types: - - **Flux Script**: Use `__PREVIOUS_RESULT__` to build from data in the previous cell, enter a Flux script to transform your data. - - **Downsample**: Window data by time and apply an aggregate to each window to downsample data. For more information, see [Downsample data with notebooks](/influxdb/cloud/notebooks/downsample/). -2. Select **Preview** (**CTRL + Enter**) or **Run** in the upper left dropdown menu. - -{{% warn %}} -If your cell contains a custom script that uses any output function to write data to InfluxDB (for example: the to() function) or send it to a third party service, clicking Preview will write data. -{{% /warn %}} - -### Add a pass-through cell - -Select one of the following pass-through cell-types: - -- To change visability and name of columns, select [Column Editor](#column-editor). -- To create a visualization of your data, select [Visualization](#visualization). For details on available visualization types and how to use them, see [Visualization types](/influxdb/cloud/visualize-data/visualization-types/). -- To enter explanatory notes, select [Markdown](#markdown). - -#### Column Editor - -- Click the toggle to hide or view your column. -- Rename your columns by hovering over the column name and pressing the pencil icon. - -#### Visualization - -- To change your visualization type, click the second dropdown menu at the top of the cell. -- (For histogram only) To specify values, click **Select**. -- To configure the visualization, click **Configure**. -- To download results as an annotated CSV file, click the **CSV** button. -- To export to the dashboard, click **Export to Dashboard**. - -#### Markdown - -- Type in notes as needed. - -### Add an output cell - -Select one of the following output cell-types: - -- To recieve a notification, select [Alert](#alert) and complete the steps below. -- To write output to a bucket, select [Output to Bucket](#output-to-bucket) and complete the steps below. -- To create a task, select [Schedule](#schedule) and complete the steps below. - -#### Alert - -1. Enter a time range to automatically check the data and enter your query offset. -2. Customize the conditions to send an alert. -3. Select an endpoint to receive an alert: - - Slack and a Slack Channel - - HTTP post - - Pager Duty -4. (Optional) Personalize your message. By default, the message is "${strings.title(v: r._type)} for ${r._source_measurement} triggered at ${time(v: r._source_timestamp)}!" -5. Click **Export as Task** to create your alarm. - -#### Output to bucket - -1. Select a bucket. -2. Click **Preview** to see what would be written to the bucket without commiting, or click **Run** in the upper left to write, or select **Export as Task** to schedule your output as a task. - -#### Schedule - -1. Enter a time and an offset to schedule the task. -2. Click **Export as Task** to save. - -### View and edit Flux script in a cell -Convert your notebook cells into raw Flux script to view and edit the code. Conversion to Flux is available for the following cell types: - - **Inputs: Metric Selector** - - **Transform: Column Editor** and **Downsample** - -1. Click the overflow menu icon in the cell you want to view as Flux, and then select **Convert to |> Flux**. You won't be able to undo this step. - A Flux cell appears with underlying script for the selected cell. -3. View and edit the Flux script as needed. +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/notebooks/downsample.md b/content/influxdb/cloud/notebooks/downsample.md index b1cc72dc0c..70cd68d60a 100644 --- a/content/influxdb/cloud/notebooks/downsample.md +++ b/content/influxdb/cloud/notebooks/downsample.md @@ -33,7 +33,7 @@ Learn how to create a notebook that downsamples data—walk through the followin - Select the **mean** function from the aggregate selector in the upper-right. 3. Add a **Downsample** cell to bring in data from the previous cell and downsample it. - Select an aggregate function from the **Apply aggregate** dropdown menu. - - Enter a window period. + - Enter a window period. 4. Add an **Output to Bucket** cell, and then select the destination bucket for your downsampled data. 5. Add a **Markdown** cell to add a note to your team about what this notebook does. For example, the cell might say, "Downsample to one value per hour so we can do week-over-week performance. Sending data to downsample bucket." 6. Click **Preview** in the upper left to verify that your notebook runs and preview the output. diff --git a/content/influxdb/cloud/notebooks/manage-notebooks.md b/content/influxdb/cloud/notebooks/manage-notebooks.md index 54688e2fdd..305a3ded41 100644 --- a/content/influxdb/cloud/notebooks/manage-notebooks.md +++ b/content/influxdb/cloud/notebooks/manage-notebooks.md @@ -9,21 +9,4 @@ menu: parent: Notebooks --- -View, update, and delete notebooks in the UI. - -## View or update notebooks -1. In the navigation menu on the left, click **Notebooks**. - - {{< nav-icon "notebooks" >}} - - A list of notebooks appears. -2. Click a notebook to open it. -3. To update, edit the notebook's cells and content. Changes are saved automatically. - -## Delete a notebook -1. In the navigation menu on the left, click **Notebooks**. - - {{< nav-icon "notebooks" >}} -2. Hover over a notebook in the list that appears. -3. Click **Delete Notebook**. -4. Click **Confirm**. +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/notebooks/overview.md b/content/influxdb/cloud/notebooks/overview.md index d444b75d53..8905563d74 100644 --- a/content/influxdb/cloud/notebooks/overview.md +++ b/content/influxdb/cloud/notebooks/overview.md @@ -1,7 +1,7 @@ --- title: Overview of notebooks description: > - Learn about the building blocks of a notebook. + Learn about the building blocks of a notebook. weight: 101 influxdb/cloud/tags: menu: @@ -10,76 +10,4 @@ menu: parent: Notebooks --- -Learn about the building blocks of a notebook, how notebooks can help show how data is processed, and discover some common use cases. - -To use different notebook cell types, controls, and uses to process data, see: -- [Notebook concepts](/influxdb/cloud/notebooks/overview/#notebook-concepts) -- [Notebook controls](/influxdb/cloud/notebooks/overview/#notebook-controls) -- [Notebook cell types](/influxdb/cloud/notebooks/overview/#notebook-cell-types) - -## Notebook concepts - -{{< youtube Rs16uhxK0h8 >}} - -Using notebooks, you can: - -- Create documents with live code, equations, visualizations, and explanatory notes. -- Create dashboard cells or scheduled tasks. -- Clean and downsample data. -- Build runbooks. -- Document data processing steps. - -## Notebook controls - -The following options appear at the top of each notebook. - -### Preview/Run mode - -- Select **Preview** (or press **Control+Enter**) to display results of each cell without writing data. Helps to verify that cells return expected results before writing data. -- Select **Run** mode displays results of each cell and writes data to the selected bucket. - -### Presentation mode - -Display notebooks in full screen with Presentation mode, hiding the left and top navigation menus so only the cells appear. This mode might be helpful, for example, for stationary screens dedicated to monitoring visualizations. - -### Local or UTC timezone - -Click the timezone dropdown list to select a timezone to use for the dashboard. Select either the local time (default) or UTC. - -### Time range - -Select from the options in the dropdown list or select **Custom Time Range** to enter a custom time range with precision up to nanoseconds. - -## Notebook cell types - -The following cell types are available for your notebook: -- [Inputs](#inputs) -- [Transform](#transform) -- [Pass-through](#pass-through) -- [Output](#output) - -### Inputs - -At least one input cell is required in a notebook for other cells to run. - -- **Metric Selector**: Filter out your data using a single list. -- **Query Builder**: Filter out your data using lists separated by group keys. - -### Transform - -- **Flux Script**: -Modify your data with Flux Script. `__PREVIOUS_RESULT__` refers to your previous inputs from the Metric Selector. -- **Downsample**: -Downsample data through aggregates. - -### Pass-through - -- **Column Editor**: Modify column visibility and naming. -- **Markdown**: Create explanatory notes or other information for yourself or one of your team members. -- **Visualization**: Represents your data in visual formats such as graphs or charts. - -### Output - -- **Notification**: Set up alerts. -- **Output to Bucket**: In **Preview** mode, this cell represents what would be written if the data was going to be committed to a bucket. -- **Output: Schedule**: Run tasks at specific times. +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/notebooks/troubleshoot-notebooks.md b/content/influxdb/cloud/notebooks/troubleshoot-notebooks.md index 4d14702840..bebc2efeb2 100644 --- a/content/influxdb/cloud/notebooks/troubleshoot-notebooks.md +++ b/content/influxdb/cloud/notebooks/troubleshoot-notebooks.md @@ -9,11 +9,4 @@ menu: parent: Notebooks --- -### No measurements appear in my bucket even though there's data in it. -Try changing the time range. You might have measurements prior to the time range you selected. For example, if the selected time range is `Past 1h` and the last write happened 16 hours ago, you'd need to change the time range to `Past 24h` (or more) to see your data. - -### "No bucket exists" error message appears. -This error appears when the Buckets API endpoint returns a list of bucket and you don’t have access to that bucket. Verify that you have access permissions to the bucket that you're trying to query or write to. - -### Metric selector crashes. -This can occur with high-cardinality buckets when there's too much data for the browser. To decrease the amount of data in your bucket, see how to [resolve high series cardinality](/influxdb/cloud/write-data/best-practices/resolve-high-cardinality/). +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/api/influxdb-1x/_index.md b/content/influxdb/cloud/reference/api/influxdb-1x/_index.md index dc43388cad..8ed8fc6760 100644 --- a/content/influxdb/cloud/reference/api/influxdb-1x/_index.md +++ b/content/influxdb/cloud/reference/api/influxdb-1x/_index.md @@ -42,7 +42,7 @@ token to InfluxDB. ##### Syntax ```sh -Authorization: Token +Authorization: Token INFLUXDB_API_TOKEN ``` ##### Example @@ -85,7 +85,7 @@ Use the `Authorization` header with the `Basic` scheme to provide username and p ##### Syntax ```sh -Authorization: Basic : +Authorization: Basic INFLUX_USERNAME:INFLUX_API_TOKEN ``` ##### Example @@ -97,9 +97,10 @@ Authorization: Basic : {{% /code-tabs %}} {{% code-tab-content %}} ```sh -{{% get-shared-text "api/v1-compat/auth/oss/basic-auth.sh" %}} +{{% get-shared-text "api/v1-compat/auth/cloud/basic-auth.sh" %}} ``` {{% /code-tab-content %}} + {{% code-tab-content %}} ```js {{% get-shared-text "api/v1-compat/auth/cloud/basic-auth.js" %}} @@ -107,6 +108,10 @@ Authorization: Basic : {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} +Replace the following: +- *`exampleuser@influxdata.com`*: the email address that you signed up with +- *`INFLUX_API_TOKEN`*: your [InfluxDB API token](/influxdb/cloud/reference/glossary/#token) + #### Query string authentication Use InfluxDB 1.x API parameters to provide username and password credentials through the query string. @@ -120,8 +125,8 @@ Use InfluxDB 1.x API parameters to provide username and password credentials thr ##### Syntax ```sh - /query/?u=&p= - /write/?u=&p= + /query/?u=INFLUX_USERNAME&p=INFLUX_API_TOKEN + /write/?u=INFLUX_USERNAME&p=INFLUX_API_TOKEN ``` ##### Example @@ -133,16 +138,20 @@ Use InfluxDB 1.x API parameters to provide username and password credentials thr {{% /code-tabs %}} {{% code-tab-content %}} ```sh -{{% get-shared-text "api/v1-compat/auth/oss/querystring-auth.sh" %}} +{{% get-shared-text "api/v1-compat/auth/cloud/querystring-auth.sh" %}} ``` {{% /code-tab-content %}} {{% code-tab-content %}} ```js -{{% get-shared-text "api/v1-compat/auth/oss/querystring-auth.js" %}} +{{% get-shared-text "api/v1-compat/auth/cloud/querystring-auth.js" %}} ``` {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} +Replace the following: +- *`exampleuser@influxdata.com`*: the email address that you signed up with +- *`INFLUX_API_TOKEN`*: your [InfluxDB API token](/influxdb/cloud/reference/glossary/#token) + ## InfluxQL support The compatibility API supports InfluxQL, with the following caveats: diff --git a/content/influxdb/cloud/reference/cli/influx/_index.md b/content/influxdb/cloud/reference/cli/influx/_index.md index 7327f0cf74..d5c914457f 100644 --- a/content/influxdb/cloud/reference/cli/influx/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/_index.md @@ -10,109 +10,8 @@ menu: parent: Command line tools weight: 101 influxdb/cloud/tags: [cli] +related: + - /influxdb/cloud/tools/clis/ --- -The `influx` command line interface (CLI) includes commands to manage many aspects of InfluxDB, -including buckets, organizations, users, tasks, etc. - -For information about setting up and configuring the `influx` CLI, see [Download, install, and use the influx CLI](/influxdb/cloud/sign-up/#optional-download-install-and-use-the-influx-cli). - -## Usage - -``` -influx [flags] -influx [command] -``` - -### Provide required authentication credentials -To avoid having to pass your InfluxDB **host**, **API token**, and **organization** -with each command, store them in an `influx` CLI configuration (config). -`influx` commands that require these credentials automatically retrieve these -credentials from the active config. - -Use the [`influx config create` command](/influxdb/cloud/reference/cli/influx/config/create/) -to create an `influx` CLI config and set it as active: - -```sh -influx config create --config-name \ - --host-url http://localhost:8086 \ - --org \ - --token \ - --active -``` - -For more information about managing CLI configurations, see the -[`influx config` documentation](/influxdb/cloud/reference/cli/influx/config/). - -## Commands - -| Command | Description | -|:------- |:----------- | -| [apply](/influxdb/cloud/reference/cli/influx/apply) | Apply an InfluxDB template | -| [auth](/influxdb/cloud/reference/cli/influx/auth) | API token management commands | -| [backup](/influxdb/cloud/reference/cli/influx/backup) | Back up data | -| [bucket](/influxdb/cloud/reference/cli/influx/bucket) | Bucket management commands | -| [completion](/influxdb/cloud/reference/cli/influx/completion) | Generate completion scripts | -| [config](/influxdb/cloud/reference/cli/influx/config) | Configuration management commands | -| [dashboards](/influxdb/cloud/reference/cli/influx/dashboards) | List dashboards | -| [delete](/influxdb/cloud/reference/cli/influx/delete) | Delete points from InfluxDB | -| [export](/influxdb/cloud/reference/cli/influx/export) | Export resources as a template | -| [help](/influxdb/cloud/reference/cli/influx/help) | Help about any command | -| [org](/influxdb/cloud/reference/cli/influx/org) | Organization management commands | -| [ping](/influxdb/cloud/reference/cli/influx/ping) | Check the InfluxDB `/health` endpoint | -| [query](/influxdb/cloud/reference/cli/influx/query) | Execute a Flux query | -| [secret](/influxdb/cloud/reference/cli/influx/secret) | Manage secrets | -| [setup](/influxdb/cloud/reference/cli/influx/setup) | Create default username, password, org, bucket, etc. | -| [stacks](/influxdb/cloud/reference/cli/influx/stacks) | Manage InfluxDB stacks | -| [task](/influxdb/cloud/reference/cli/influx/task) | Task management commands | -| [telegrafs](/influxdb/cloud/reference/cli/influx/telegrafs) | Telegraf configuration management commands | -| [template](/influxdb/cloud/reference/cli/influx/template) | Summarize and validate an InfluxDB template | -| [user](/influxdb/cloud/reference/cli/influx/user) | User management commands | -| [v1](/influxdb/cloud/reference/cli/influx/v1) | Work with the v1 compatibility API | -| [version](/influxdb/cloud/reference/cli/influx/version) | Print the influx CLI version | -| [write](/influxdb/cloud/reference/cli/influx/write) | Write points to InfluxDB | - -## Flags - -| Flag | | Description | -|:---- |:--- |:----------- | -| `-h` | `--help` | Help for the `influx` command | -| | `--http-debug` | Inspect communication with InfluxDB servers | - -### Flag patterns and conventions -The `influx` CLI uses the following patterns and conventions: - -- [Mapped environment variables](#mapped-environment-variables) -- [Shorthand and longhand flags](#shorthand-and-longhand-flags) -- [Flag input types](#flag-input-types) - -#### Mapped environment variables -`influx` CLI flags mapped to environment variables are listed in the **Mapped to** column. -Mapped flags inherit the value of the environment variable. -To override environment variables, set the flag explicitly in your command. - -#### Shorthand and longhand flags -Many `influx` CLI flags support both shorthand and longhand forms. - -- **shorthand:** a shorthand flag begins with a single hyphen followed by a single letter (for example: `-c`). -- **longhand:** a longhand flag starts with two hyphens followed by a multi-letter, - hyphen-spaced flag name (for example: `--active-config`). - -Commands can use both shorthand and longhand flags in a single execution. - -#### Flag input types -`influx` CLI flag input types are listed in each the table of flags for each command. -Flags support the following input types: - -##### string -Text string, but the flag can be used **only once** per command execution. - -##### stringArray -Single text string, but the flag can be used **multiple times** per command execution. - -##### integer -Sequence of digits representing an integer value. - -##### duration -Length of time represented by an integer and a duration unit -(`1ns`, `1us`, `1µs`, `1ms`, `1s`, `1m`, `1h`, `1d`, `1w`). +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/apply/_index.md b/content/influxdb/cloud/reference/cli/influx/apply/_index.md index 47f43c82c3..ac018a45c2 100644 --- a/content/influxdb/cloud/reference/cli/influx/apply/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/apply/_index.md @@ -12,6 +12,7 @@ influxdb/cloud/tags: [templates] related: - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+] --- {{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/reference/cli/influx/auth/_index.md b/content/influxdb/cloud/reference/cli/influx/auth/_index.md index 289a8f0c6b..997d5d9d4e 100644 --- a/content/influxdb/cloud/reference/cli/influx/auth/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/auth/_index.md @@ -11,6 +11,7 @@ cascade: related: - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/auth/create.md b/content/influxdb/cloud/reference/cli/influx/auth/create.md index 4d6cc74929..cf7fb65b35 100644 --- a/content/influxdb/cloud/reference/cli/influx/auth/create.md +++ b/content/influxdb/cloud/reference/cli/influx/auth/create.md @@ -6,6 +6,7 @@ menu: name: influx auth create parent: influx auth weight: 201 +updated_in: CLI v2.2.0 --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/backup/_index.md b/content/influxdb/cloud/reference/cli/influx/backup/_index.md index 83bddbc860..e4c1c237fc 100644 --- a/content/influxdb/cloud/reference/cli/influx/backup/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/backup/_index.md @@ -10,13 +10,15 @@ influxdb/cloud/tags: [backup] related: - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+, InfluxDB OSS only] +updated_in: CLI v2.0.2 --- {{% note %}} -#### Available with InfluxDB OSS 2.x only +#### Works with InfluxDB OSS 2.x The `influx backup` command works with **InfluxDB OSS 2.x**, but does not work with **InfluxDB Cloud**. For information about backing up data in InfluxDB Cloud, see -[InfluxDB Cloud durabilty](/influxdb/cloud/reference/internals/durability/) or +[InfluxDB Cloud durability](/influxdb/cloud/reference/internals/durability/) or [contact InfluxData Support](mailto:support@influxdata.com). {{% /note %}} diff --git a/content/influxdb/cloud/reference/cli/influx/bucket-schema/_index.md b/content/influxdb/cloud/reference/cli/influx/bucket-schema/_index.md index 76a4d837f5..20b81fc4b8 100644 --- a/content/influxdb/cloud/reference/cli/influx/bucket-schema/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/bucket-schema/_index.md @@ -13,28 +13,7 @@ cascade: - /influxdb/cloud/organizations/buckets/ - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.1.0+] --- -The `influx bucket-schema` command and its subcommands manage -schemas for InfluxDB buckets. - -## Usage - -``` -influx bucket-schema [flags] -influx bucket-schema [command] -``` - -## Subcommands - -| Subcommand | Description | -|:---------- |:----------- | -| [create](/influxdb/cloud/reference/cli/influx/bucket-schema/create) | Create a bucket schema | -| [list](/influxdb/cloud/reference/cli/influx/bucket-schema/list) | List bucket schemas | -| [update](/influxdb/cloud/reference/cli/influx/bucket-schema/update) | Update a bucket schema | - -## Flags - -| Flag | | Description | Input type | {{< cli/mapped >}} | -|:---- |:--- |:----------- |:---------- |:------------------ | -| `-h` | `--help` | Help for the `bucket-schema` command | | | +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/bucket-schema/create.md b/content/influxdb/cloud/reference/cli/influx/bucket-schema/create.md index 896765467b..ffb39d4d8a 100644 --- a/content/influxdb/cloud/reference/cli/influx/bucket-schema/create.md +++ b/content/influxdb/cloud/reference/cli/influx/bucket-schema/create.md @@ -10,80 +10,4 @@ related: - /influxdb/cloud/organizations/buckets/bucket-schema --- -The `influx bucket-schema create` command sets the schema for a measurement in an InfluxDB bucket that has the [`explicit` schema-type](/influxdb/cloud/reference/cli/influx/bucket/create/#create-a-bucket-with-an-explicit-schema). - -## Usage - -```sh -influx bucket-schema create [flags] -``` - -## Flags - -| Flag | | Description | Input type | {{< cli/mapped >}} | -|:-----|:--------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------:|:----------------------| -| `-c` | `--active-config` | CLI configuration to use for command | string | | -| `-n` | `--bucket` | ({{< req >}}) Bucket name (mutually exclusive with `--bucket-id`) | string | | -| `-i` | `--bucket-id` | ({{< req >}}) Bucket ID (mutually exclusive with `--bucket`) | string | | -| | `--columns-file` | ({{< req >}}) Path to column definitions file. For more information, see [Create a columns file](/influxdb/cloud/reference/cli/influx/bucket-schema/create/#create-a-columns-file). | string | | -| | `--columns-format` | Columns file format (`csv`, `ndjson`, `json`, default: `auto`). For more information, see [Create a schema with columns format](#create-a-schema-with-columns-format) | string | | -| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | -| `-x` | `--extended-output` | Print column information for each measurement schema (default: false) | | | -| `-h` | `--help` | Help for the `create` command | | | -| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | -| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | -| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | -| `-n` | `--name` | ({{< req >}}) Measurement name | string | | -| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | -| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | -| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | -| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | - - -## Examples - -{{< cli/influx-creds-note >}} - -- [Create a schema using the influx CLI](#create-a-schema-using-the-influx-cli) -- [Create a schema and print column information](#create-a-schema-and-print-column-information) -- [Create a schema with columns format](#create-a-schema-with-columns-format) - -## Create a schema using the influx CLI - -```sh -influx bucket-schema create \ - --bucket example-bucket \ - --name temperature \ - --columns-file columns.csv -``` - -## Create a schema and print column information - -```sh -influx bucket-schema create \ - --bucket example-bucket \ - --name cpu \ - --columns-file columns.csv \ - --extended-output -``` - -## Create a schema with columns format - -By default, InfluxDB attempts to detect the **columns file** format. -If your file's extension doesn't match the format, set the format with the [`columns-format` flag](/influxdb/cloud/reference/cli/influx/bucket-schema/create). - -```sh -influx bucket-schema create \ - --bucket example-bucket \ - --name cpu \ - --columns-file columns.json \ - --columns-format ndjson -``` - -```sh -influx bucket-schema create \ - --bucket example-bucket \ - --name cpu \ - --columns-file columns.txt \ - --columns-format csv -``` +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/bucket-schema/list.md b/content/influxdb/cloud/reference/cli/influx/bucket-schema/list.md index 31341c87aa..524e47bd4e 100644 --- a/content/influxdb/cloud/reference/cli/influx/bucket-schema/list.md +++ b/content/influxdb/cloud/reference/cli/influx/bucket-schema/list.md @@ -10,50 +10,4 @@ related: - /influxdb/cloud/organizations/buckets/bucket-schema --- -The `influx bucket-schema list` command lists the schemas of an -InfluxDB bucket that has the [`explicit` schema-type](/influxdb/cloud/reference/cli/influx/bucket/create/#create-a-bucket-with-an-explicit-schema). - -## Usage - -```sh -influx bucket-schema list [flags] -``` - -## Flags - -| Flag | | Description | Input type | {{< cli/mapped >}} | -|:-----|:--------------------|:----------------------------------------------------------------------|:----------:|:----------------------| -| `-c` | `--active-config` | CLI configuration to use for command | string | | -| `-n` | `--bucket` | Bucket name (mutually exclusive with `--bucket-id`) | string | | -| `-i` | `--bucket-id` | Bucket ID (mutually exclusive with `--bucket`) | string | | -| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | -| `-x` | `--extended-output` | Print column information for each measurement schema (default: false) | | | -| `-h` | `--help` | Help for the `create` command | | | -| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | -| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | -| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | -| `-n` | `--name` | Measurement name | string | | -| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | -| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | -| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | -| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | - -## Examples - -{{< cli/influx-creds-note >}} - -## List all schemas of a bucket and print column information - -```sh -influx bucket-schema list \ - --bucket example-bucket - --extended-output -``` - -## Print column details for a single measurement -```sh -influx bucket-schema list \ - --bucket example-bucket \ - --name cpu \ - --extended-output -``` +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/bucket-schema/update.md b/content/influxdb/cloud/reference/cli/influx/bucket-schema/update.md index 942a52f1a3..949b686f6f 100644 --- a/content/influxdb/cloud/reference/cli/influx/bucket-schema/update.md +++ b/content/influxdb/cloud/reference/cli/influx/bucket-schema/update.md @@ -10,87 +10,4 @@ related: - /influxdb/cloud/organizations/buckets/bucket-schema --- -The `influx bucket-schema update` command updates the schema of an InfluxDB bucket that has the [`explicit` schema-type](/influxdb/cloud/reference/cli/influx/bucket/create/#create-a-bucket-with-an-explicit-schema). - -`bucket-schema update` requires a bucket with at least one defined schema. - -## Usage - -```sh -influx bucket-schema update [flags] -``` - -##### Supported operations -- Adding new columns to a schema - -##### Unsupported operations -- Modify existing columns in a schema -- Delete columns from a schema - -## Flags - -| Flag | | Description | Input type | {{< cli/mapped >}} | -|:-----|:--------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------:|:----------------------| -| `-c` | `--active-config` | CLI configuration to use for command | string | | -| `-n` | `--bucket` | ({{< req >}}) Bucket name (mutually exclusive with `--bucket-id`) | string | | -| `-i` | `--bucket-id` | ({{< req >}}) Bucket ID (mutually exclusive with `--bucket`) | string | | -| | `--columns-file` | ({{< req >}}) Path to column definitions file. For more information, see [Create a columns file](/influxdb/cloud/reference/cli/influx/bucket-schema/create/#create-a-columns-file). | string | | -| | `--columns-format` | Columns file format (`csv`, `ndjson`, `json`, default: `auto`). For more information, see [Update a schema with columns format](#update-a-schema-with-columns-format) | string | | -| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | -| `-x` | `--extended-output` | Print column information for each measurement schema (default: false) | | | -| `-h` | `--help` | Help for the `create` command | | | -| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | -| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | -| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | -| `-n` | `--name` | ({{< req >}}) Measurement name | string | | -| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | -| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | -| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | -| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | - -## Examples - -{{< cli/influx-creds-note >}} - -- [Update a schema using the influx CLI](#update-a-schema-using-the-influx-cli) -- [Update a schema and print column information](#update-a-schema-and-print-column-information) -- [Update a schema with columns format](#update-a-schema-specifying-the-columns-format) - -## Update a schema using the influx CLI - -```sh -influx bucket-schema update \ - --bucket example-bucket \ - --name temperature \ - --columns-file columns.csv -``` - -## Update a schema and print column information -```sh -influx bucket-schema update \ - --bucket example-bucket \ - --name cpu \ - --columns-file columns.csv \ - -extended-output -``` - -## Update a schema with columns format - -By default, InfluxDB attempts to detect the **columns file** format. -If your file's extension doesn't match the format, set the format with the `columns-format` flag. - -```sh -influx bucket-schema update \ - --bucket example-bucket \ - --name cpu \ - --columns-file columns.json \ - --columns-format ndjson -``` - -```sh -influx bucket-schema update \ - --bucket example-bucket \ - --name cpu \ - --columns-file columns.txt \ - --columns-format csv -``` +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/bucket/_index.md b/content/influxdb/cloud/reference/cli/influx/bucket/_index.md index 07b56f64a9..760d71f7a7 100644 --- a/content/influxdb/cloud/reference/cli/influx/bucket/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/bucket/_index.md @@ -12,6 +12,7 @@ cascade: - /influxdb/cloud/organizations/buckets/ - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/bucket/create.md b/content/influxdb/cloud/reference/cli/influx/bucket/create.md index c4196b3979..de0787f4c4 100644 --- a/content/influxdb/cloud/reference/cli/influx/bucket/create.md +++ b/content/influxdb/cloud/reference/cli/influx/bucket/create.md @@ -12,6 +12,7 @@ related: - /influxdb/cloud/organizations/buckets/create-buckets/ - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +updated_in: CLI v2.1.0 --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/bucket/list.md b/content/influxdb/cloud/reference/cli/influx/bucket/list.md index c28714c310..bc5b3d5593 100644 --- a/content/influxdb/cloud/reference/cli/influx/bucket/list.md +++ b/content/influxdb/cloud/reference/cli/influx/bucket/list.md @@ -6,6 +6,7 @@ menu: name: influx bucket list parent: influx bucket weight: 201 +updated_in: CLI v2.2.0 --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/completion/_index.md b/content/influxdb/cloud/reference/cli/influx/completion/_index.md index 833bda2f0b..c5840b5b19 100644 --- a/content/influxdb/cloud/reference/cli/influx/completion/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/completion/_index.md @@ -12,6 +12,7 @@ influxdb/cloud/tags: [cli, tools] related: - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/config/_index.md b/content/influxdb/cloud/reference/cli/influx/config/_index.md index 8841aa6651..99ab3cec8f 100644 --- a/content/influxdb/cloud/reference/cli/influx/config/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/config/_index.md @@ -11,6 +11,7 @@ cascade: related: - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/dashboards/_index.md b/content/influxdb/cloud/reference/cli/influx/dashboards/_index.md index 1a0bb071df..57e3657364 100644 --- a/content/influxdb/cloud/reference/cli/influx/dashboards/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/dashboards/_index.md @@ -11,6 +11,7 @@ influxdb/cloud/tags: [telegraf] related: - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/delete/_index.md b/content/influxdb/cloud/reference/cli/influx/delete/_index.md index 4153fe8358..dcd6ed45f5 100644 --- a/content/influxdb/cloud/reference/cli/influx/delete/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/delete/_index.md @@ -12,6 +12,8 @@ related: - /influxdb/cloud/reference/syntax/delete-predicate - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.3+] +updated_in: CLI v2.2.0 --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/export/_index.md b/content/influxdb/cloud/reference/cli/influx/export/_index.md index 759400ecf3..c3c1205e04 100644 --- a/content/influxdb/cloud/reference/cli/influx/export/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/export/_index.md @@ -10,6 +10,7 @@ cascade: - /influxdb/cloud/influxdb-templates/create/ - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/export/all.md b/content/influxdb/cloud/reference/cli/influx/export/all.md index f78352ddeb..9cfaf17944 100644 --- a/content/influxdb/cloud/reference/cli/influx/export/all.md +++ b/content/influxdb/cloud/reference/cli/influx/export/all.md @@ -8,6 +8,8 @@ menu: weight: 201 related: - /influxdb/cloud/influxdb-templates/create/ + - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/help/_index.md b/content/influxdb/cloud/reference/cli/influx/help/_index.md index 9d7a4509e0..f84a5ec013 100644 --- a/content/influxdb/cloud/reference/cli/influx/help/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/help/_index.md @@ -9,6 +9,7 @@ weight: 101 related: - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/org/_index.md b/content/influxdb/cloud/reference/cli/influx/org/_index.md index ef948752c7..e191b551ef 100644 --- a/content/influxdb/cloud/reference/cli/influx/org/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/org/_index.md @@ -11,6 +11,7 @@ cascade: related: - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/org/create.md b/content/influxdb/cloud/reference/cli/influx/org/create.md index 91f919144e..d4e33a8233 100644 --- a/content/influxdb/cloud/reference/cli/influx/org/create.md +++ b/content/influxdb/cloud/reference/cli/influx/org/create.md @@ -6,6 +6,15 @@ menu: name: influx org create parent: influx org weight: 201 +metadata: [influx CLI 2.0.0+, InfluxDB OSS only] --- +{{% note %}} +#### Works with InfluxDB OSS 2.x +The `influx org create` command works with **InfluxDB OSS 2.x**, but does not work with **InfluxDB Cloud**. +New organizations are created for each new InfluxDB account. +For information about creating an InfluxDB Cloud account, see +[sign up for InfluxDB Cloud](/influxdb/cloud/sign-up/). +{{% /note %}} + {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/org/delete.md b/content/influxdb/cloud/reference/cli/influx/org/delete.md index 066a77dca5..2fff051ab1 100644 --- a/content/influxdb/cloud/reference/cli/influx/org/delete.md +++ b/content/influxdb/cloud/reference/cli/influx/org/delete.md @@ -6,6 +6,15 @@ menu: name: influx org delete parent: influx org weight: 201 +metadata: [influx CLI 2.0.0+, InfluxDB OSS only] --- +{{% note %}} +#### Works with InfluxDB OSS 2.x +The `influx org delete` command works with **InfluxDB OSS 2.x**, but does not work with **InfluxDB Cloud**. +An organizations is associated with your InfluxDB account. +For information about removing your InfluxDB Cloud account and its organization, +see [Cancel your InfluxDB Cloud subscription](/influxdb/cloud/account-management/offboarding/). +{{% /note %}} + {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/org/members/_index.md b/content/influxdb/cloud/reference/cli/influx/org/members/_index.md index b247ca02c1..38aed32a52 100644 --- a/content/influxdb/cloud/reference/cli/influx/org/members/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/org/members/_index.md @@ -6,10 +6,11 @@ menu: name: influx org members parent: influx org weight: 201 +metadata: [influx CLI 2.0.0+, InfluxDB OSS only] --- {{% note %}} -#### Available with InfluxDB OSS 2.x only +#### Works with InfluxDB OSS 2.x The `influx org members` command works with **InfluxDB OSS 2.x**, but does not work with **InfluxDB Cloud**. For information about managing users in your InfluxDB Cloud organization, see [Manage multiple users](/influxdb/cloud/account-management/multi-user/). diff --git a/content/influxdb/cloud/reference/cli/influx/ping/_index.md b/content/influxdb/cloud/reference/cli/influx/ping/_index.md index 2002cec3b0..2e2659c43c 100644 --- a/content/influxdb/cloud/reference/cli/influx/ping/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/ping/_index.md @@ -12,10 +12,11 @@ influxdb/cloud/tags: [ping, health] related: - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+, InfluxDB OSS only] --- {{% note %}} -#### Available with InfluxDB OSS 2.x only +#### Works with InfluxDB OSS 2.x The `influx ping` command works with **InfluxDB OSS 2.x**, but does not work with **InfluxDB Cloud**. {{% /note %}} diff --git a/content/influxdb/cloud/reference/cli/influx/query/_index.md b/content/influxdb/cloud/reference/cli/influx/query/_index.md index 522f5b130e..8e2fc7bb24 100644 --- a/content/influxdb/cloud/reference/cli/influx/query/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/query/_index.md @@ -14,6 +14,8 @@ related: - /influxdb/cloud/query-data/execute-queries/influx-query/ - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+] +updated_in: CLI v2.0.5 --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/restore/index.md b/content/influxdb/cloud/reference/cli/influx/restore/index.md index 12ca4c1fcf..87772a175e 100644 --- a/content/influxdb/cloud/reference/cli/influx/restore/index.md +++ b/content/influxdb/cloud/reference/cli/influx/restore/index.md @@ -9,77 +9,16 @@ weight: 101 related: - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+] +updated_in: CLI v2.0.7 --- {{% note %}} -#### Available with InfluxDB OSS 2.x only +#### Works with InfluxDB OSS 2.x The `influx restore` command works with **InfluxDB OSS 2.x**, but does not work with **InfluxDB Cloud**. For information about restoring data in InfluxDB Cloud, see -[InfluxDB Cloud durabilty](/influxdb/cloud/reference/internals/durability/) and +[InfluxDB Cloud durability](/influxdb/cloud/reference/internals/durability/) and [contact InfluxData Support](mailto:support@influxdata.com). {{% /note %}} -The `influx restore` command restores backup data and metadata from an InfluxDB OSS backup directory. - -### The restore process -When restoring data from a backup file set, InfluxDB temporarily moves existing -data and metadata while `restore` runs. -After `restore` completes, the temporary data is deleted. -If the restore process fails, InfluxDB preserves the data in the temporary location. - -_For information about recovering from a failed restore process, see -[Restore data](/influxdb/v2.0/backup-restore/restore/#recover-from-a-failed-restore)._ - -## Usage - -``` -influx restore [flags] -``` - -## Flags - -| Flag | | Description | Input type | {{< cli/mapped >}} | -|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| -| `-c` | `--active-config` | CLI configuration to use for command | string | | -| `-b` | `--bucket` | Name of the bucket to restore (mutually exclusive with `--bucket-id`) | string | | -| | `--bucket-id` | ID of the bucket to restore (mutually exclusive with `--bucket`) | string | | -| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | -| | `--full` | Fully restore and replace all data on server | | | -| `-h` | `--help` | Help for the `restore` command | | | -| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | -| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | -| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | -| | `--new-bucket` | Name of the bucket to restore to | string | | -| | `--new-org` | Name of the organization to restore to | string | | -| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | | -| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | | -| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | -| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | - -## Examples - -{{< cli/influx-creds-note >}} - -- [Restore and replace all data](#restore-and-replace-all-data) -- [Restore backup data to an existing bucket](#restore-backup-data-to-an-existing-bucket) -- [Create a bucket and restore data to it](#create-a-bucket-and-restore-data-to-it) - -##### Restore and replace all data -```sh -influx restore --full /path/to/backup/dir/ -``` - -##### Restore backup data to an existing bucket -```sh -influx restore \ - --bucket example-bucket \ - /path/to/backup/dir/ -``` - -##### Create a bucket and restore data to it -```sh -influx restore \ - --new-bucket new-example-bucket \ - /path/to/backup/dir/ -``` - +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/reference/cli/influx/secret/_index.md b/content/influxdb/cloud/reference/cli/influx/secret/_index.md index 2e5c1110b0..5f783b3c1d 100644 --- a/content/influxdb/cloud/reference/cli/influx/secret/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/secret/_index.md @@ -6,12 +6,13 @@ menu: name: influx secret parent: influx weight: 101 -influxdb/cloud/tags: [secrets] cascade: -related: - - /influxdb/cloud/security/secrets/ - - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + influxdb/cloud/tags: [secrets] + related: + - /influxdb/cloud/security/secrets/ + - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/secret/delete.md b/content/influxdb/cloud/reference/cli/influx/secret/delete.md index d869ebaffa..7628b60af8 100644 --- a/content/influxdb/cloud/reference/cli/influx/secret/delete.md +++ b/content/influxdb/cloud/reference/cli/influx/secret/delete.md @@ -6,7 +6,6 @@ menu: name: influx secret delete parent: influx secret weight: 101 -influxdb/cloud/tags: [secrets] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/secret/list.md b/content/influxdb/cloud/reference/cli/influx/secret/list.md index 3f912a1431..5dbb36c79a 100644 --- a/content/influxdb/cloud/reference/cli/influx/secret/list.md +++ b/content/influxdb/cloud/reference/cli/influx/secret/list.md @@ -6,7 +6,6 @@ menu: name: influx secret list parent: influx secret weight: 101 -influxdb/cloud/tags: [secrets] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/secret/update.md b/content/influxdb/cloud/reference/cli/influx/secret/update.md index 05797f06da..882b983a2a 100644 --- a/content/influxdb/cloud/reference/cli/influx/secret/update.md +++ b/content/influxdb/cloud/reference/cli/influx/secret/update.md @@ -6,7 +6,6 @@ menu: name: influx secret update parent: influx secret weight: 101 -influxdb/cloud/tags: [secrets] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/setup/_index.md b/content/influxdb/cloud/reference/cli/influx/setup/_index.md index 4c9ed368b9..08718e5a48 100644 --- a/content/influxdb/cloud/reference/cli/influx/setup/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/setup/_index.md @@ -12,11 +12,13 @@ influxdb/cloud/tags: [get-started] related: - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+, InfluxDB OSS only] +updated_in: CLI v2.0.3 canonical: /{{< latest "influxdb" "v2" >}}/reference/cli/influx/setup/ --- {{% note %}} -#### Available with InfluxDB OSS 2.x only +#### Works with InfluxDB OSS 2.x The `influx setup` command initiates the setup process for **InfluxDB OSS 2.x** instances. The command does not work with **InfluxDB Cloud**. {{% /note %}} diff --git a/content/influxdb/cloud/reference/cli/influx/stacks/_index.md b/content/influxdb/cloud/reference/cli/influx/stacks/_index.md index c80533c78e..583ee35362 100644 --- a/content/influxdb/cloud/reference/cli/influx/stacks/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/stacks/_index.md @@ -14,6 +14,7 @@ cascade: - /influxdb/cloud/influxdb-templates/stacks/ - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.1+] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/stacks/update.md b/content/influxdb/cloud/reference/cli/influx/stacks/update.md index f090145521..345ca42a8e 100644 --- a/content/influxdb/cloud/reference/cli/influx/stacks/update.md +++ b/content/influxdb/cloud/reference/cli/influx/stacks/update.md @@ -7,6 +7,7 @@ menu: parent: influx stacks weight: 201 influxdb/cloud/tags: [templates] +updated_in: CLI v2.0.4 --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/task/_index.md b/content/influxdb/cloud/reference/cli/influx/task/_index.md index 546b5e1ed4..5c3db52795 100644 --- a/content/influxdb/cloud/reference/cli/influx/task/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/task/_index.md @@ -12,6 +12,7 @@ cascade: - /influxdb/cloud/process-data/ - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/task/retry-failed.md b/content/influxdb/cloud/reference/cli/influx/task/retry-failed.md index cc6068ca22..c3646d5212 100644 --- a/content/influxdb/cloud/reference/cli/influx/task/retry-failed.md +++ b/content/influxdb/cloud/reference/cli/influx/task/retry-failed.md @@ -6,6 +6,7 @@ menu: name: influx task retry-failed parent: influx task weight: 201 +metadata: [influx CLI 2.0.5+] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/telegrafs/_index.md b/content/influxdb/cloud/reference/cli/influx/telegrafs/_index.md index 0a74ca3c70..13a777df18 100644 --- a/content/influxdb/cloud/reference/cli/influx/telegrafs/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/telegrafs/_index.md @@ -14,6 +14,7 @@ cascade: - /influxdb/cloud/telegraf-configs/ - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/template/_index.md b/content/influxdb/cloud/reference/cli/influx/template/_index.md index 31e267cb1f..6cb3d9714d 100644 --- a/content/influxdb/cloud/reference/cli/influx/template/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/template/_index.md @@ -12,6 +12,7 @@ cascade: - /influxdb/cloud/influxdb-templates/ - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.1+] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/transpile/_index.md b/content/influxdb/cloud/reference/cli/influx/transpile/_index.md index 1b2f39c4cc..167ba990e0 100644 --- a/content/influxdb/cloud/reference/cli/influx/transpile/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/transpile/_index.md @@ -5,6 +5,18 @@ description: > related: - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0 – 2.0.5] +prepend: + block: warn + content: | + ### Removed in influx CLI v2.0.5 + The `influx transpile` command was removed in **v2.0.5** of the `influx` CLI. + [Use InfluxQL to query InfluxDB](/influxdb/cloud/query-data/influxql/). + For information about manually converting InfluxQL queries to Flux, see: + + - [Get started with Flux](/flux/v0.x/get-started/) + - [Query data with Flux](/influxdb/cloud/query-data/flux/) + - [Migrate continuous queries to Flux tasks](/influxdb/cloud/upgrade/v1-to-cloud/migrate-cqs/) --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/user/_index.md b/content/influxdb/cloud/reference/cli/influx/user/_index.md index 05b27e1cd5..2d3dbfe98e 100644 --- a/content/influxdb/cloud/reference/cli/influx/user/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/user/_index.md @@ -11,11 +11,12 @@ cascade: related: - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+, InfluxDB OSS only] canonical: /{{< latest "influxdb" "v2" >}}/reference/cli/influx/user/ --- {{% note %}} -#### Available with InfluxDB OSS 2.x only +#### Works with InfluxDB OSS 2.x The `influx user` command and its subcommands manage **InfluxDB OSS 2.x** users, but do not manage users in **InfluxDB Cloud**. Use the InfluxDB Cloud user interface to manage account information. diff --git a/content/influxdb/cloud/reference/cli/influx/user/create.md b/content/influxdb/cloud/reference/cli/influx/user/create.md index 2627ef3947..cdb3731217 100644 --- a/content/influxdb/cloud/reference/cli/influx/user/create.md +++ b/content/influxdb/cloud/reference/cli/influx/user/create.md @@ -10,7 +10,7 @@ canonical: /{{< latest "influxdb" "v2" >}}/reference/cli/influx/user/create/ --- {{% note %}} -#### Available with InfluxDB OSS 2.x only +#### Works with InfluxDB OSS 2.x The `influx user create` command creates users in **InfluxDB OSS 2.x**, but does not create users in **InfluxDB Cloud**. For information about inviting users into your InfluxDB Cloud organization, see diff --git a/content/influxdb/cloud/reference/cli/influx/user/delete.md b/content/influxdb/cloud/reference/cli/influx/user/delete.md index 971ae9002d..d04a074061 100644 --- a/content/influxdb/cloud/reference/cli/influx/user/delete.md +++ b/content/influxdb/cloud/reference/cli/influx/user/delete.md @@ -9,12 +9,12 @@ weight: 201 canonical: /{{< latest "influxdb" "v2" >}}/reference/cli/influx/user/delete/ --- -{{% cloud %}} -#### Available with InfluxDB OSS 2.x only +{{% note %}} +#### Works with InfluxDB OSS 2.x The `influx user delete` command deletes users from **InfluxDB OSS 2.x**, but does not delete users from **InfluxDB Cloud**. For information about removing a user from your InfluxDB Cloud organization, see [Remove a user](/influxdb/cloud/account-management/multi-user/remove-user/). -{{% /cloud %}} +{{% /note %}} {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/user/list.md b/content/influxdb/cloud/reference/cli/influx/user/list.md index 1cef651556..39bc4a1bce 100644 --- a/content/influxdb/cloud/reference/cli/influx/user/list.md +++ b/content/influxdb/cloud/reference/cli/influx/user/list.md @@ -12,11 +12,11 @@ canonical: /{{< latest "influxdb" "v2" >}}/reference/cli/influx/user/list/ --- {{% note %}} -#### Available with InfluxDB OSS 2.x only +#### Works with InfluxDB OSS 2.x The `influx user list` command lists users in **InfluxDB OSS 2.x**, but does not list users in **InfluxDB Cloud**. For information about managing InfluxDB Cloud users, see -[Manage multiple users](/influxdb/cloud/account-management/multi-user/.) +[Manage multiple users](/influxdb/cloud/account-management/multi-user/). {{% /note %}} {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/user/password.md b/content/influxdb/cloud/reference/cli/influx/user/password.md index 3ec63da833..a086e7778c 100644 --- a/content/influxdb/cloud/reference/cli/influx/user/password.md +++ b/content/influxdb/cloud/reference/cli/influx/user/password.md @@ -14,7 +14,7 @@ canonical: /{{< latest "influxdb" "v2" >}}/reference/cli/influx/user/password/ --- {{% note %}} -#### Available with InfluxDB OSS 2.x only +#### Works with InfluxDB OSS 2.x The `influx user password` command updates passwords for **InfluxDB OSS 2.x** users, but does not update passwords for **InfluxDB Cloud** accounts. To change your InfluxDB Cloud account password, see diff --git a/content/influxdb/cloud/reference/cli/influx/user/update.md b/content/influxdb/cloud/reference/cli/influx/user/update.md index 8eca317687..5c1d724046 100644 --- a/content/influxdb/cloud/reference/cli/influx/user/update.md +++ b/content/influxdb/cloud/reference/cli/influx/user/update.md @@ -11,7 +11,7 @@ canonical: /{{< latest "influxdb" "v2" >}}/reference/cli/influx/user/update/ --- {{% note %}} -#### Available with InfluxDB OSS 2.x only +#### Works with InfluxDB OSS 2.x The `influx user update` command updates users in **InfluxDB OSS 2.x**, but does not update users in **InfluxDB Cloud**. Use the InfluxDB Cloud user interface to update account information. diff --git a/content/influxdb/cloud/reference/cli/influx/v1/_index.md b/content/influxdb/cloud/reference/cli/influx/v1/_index.md index d417b6dd55..51aa64d20f 100644 --- a/content/influxdb/cloud/reference/cli/influx/v1/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/v1/_index.md @@ -11,6 +11,7 @@ cascade: related: - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/v1/auth/create.md b/content/influxdb/cloud/reference/cli/influx/v1/auth/create.md index 34d5842cb3..f9d59d9d7d 100644 --- a/content/influxdb/cloud/reference/cli/influx/v1/auth/create.md +++ b/content/influxdb/cloud/reference/cli/influx/v1/auth/create.md @@ -8,6 +8,7 @@ menu: parent: influx v1 auth weight: 101 influxdb/cloud/tags: [authorization] +updated_in: CLI v2.0.3 --- {{% cloud %}} diff --git a/content/influxdb/cloud/reference/cli/influx/v1/auth/set-password.md b/content/influxdb/cloud/reference/cli/influx/v1/auth/set-password.md index 4d1a54640c..7d1dbe05aa 100644 --- a/content/influxdb/cloud/reference/cli/influx/v1/auth/set-password.md +++ b/content/influxdb/cloud/reference/cli/influx/v1/auth/set-password.md @@ -8,6 +8,7 @@ menu: parent: influx v1 auth weight: 101 influxdb/cloud/tags: [authorization] +updated_in: CLI v2.0.3 --- {{% cloud %}} diff --git a/content/influxdb/cloud/reference/cli/influx/v1/dbrp/_index.md b/content/influxdb/cloud/reference/cli/influx/v1/dbrp/_index.md index 48f70a6510..57f234c0ec 100644 --- a/content/influxdb/cloud/reference/cli/influx/v1/dbrp/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/v1/dbrp/_index.md @@ -8,6 +8,8 @@ menu: parent: influx v1 weight: 101 influxdb/cloud/tags: [DBRP] +cascade: + metadata: [influx CLI 2.0.2+] --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/version.md b/content/influxdb/cloud/reference/cli/influx/version/_index.md similarity index 89% rename from content/influxdb/cloud/reference/cli/influx/version.md rename to content/influxdb/cloud/reference/cli/influx/version/_index.md index 01ad23f14c..724648ca78 100644 --- a/content/influxdb/cloud/reference/cli/influx/version.md +++ b/content/influxdb/cloud/reference/cli/influx/version/_index.md @@ -6,6 +6,7 @@ menu: influxdb_cloud_ref: parent: influx weight: 202 +metadata: [influx CLI 2.0.0+] --- {{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/reference/cli/influx/write/_index.md b/content/influxdb/cloud/reference/cli/influx/write/_index.md index 38641db99a..e73186fa9f 100644 --- a/content/influxdb/cloud/reference/cli/influx/write/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/write/_index.md @@ -18,6 +18,8 @@ cascade: - /influxdb/cloud/reference/syntax/annotated-csv/extended/ - /influxdb/cloud/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials - /influxdb/cloud/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+] +updated_in: CLI v2.0.5 --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/release-notes/influx-cli.md b/content/influxdb/cloud/reference/release-notes/influx-cli.md index c656b9d757..dfad094f3e 100644 --- a/content/influxdb/cloud/reference/release-notes/influx-cli.md +++ b/content/influxdb/cloud/reference/release-notes/influx-cli.md @@ -8,99 +8,4 @@ menu: name: influx CLI --- -## v2.2.0 [2021-10-21] - -This release includes three new features and bug fixes. - -## Features - -This release makes it easier to create API tokens with the `influx` CLI, adds support for viewing more than 20 buckets using `influx bucket list`, and adds a shorthand flag for bucket (`-b`) to `influx delete`. - -### Create an All-Access token in the influx CLI - -- Add the ability to use the `influx` CLI to [create an All-Access API token](/influxdb/cloud/security/tokens/create-token/#create-a-token-using-the-influx-cli) with read and write permissions to all resources in an organization. - - {{% oss-only %}} - -### Create an Operator token in the influx CLI - -- Add the ability to use the `influx` CLI to [create an Operator token](/influxdb/v2.0/security/tokens/#operator-token) with read and write permissions to all resources in all organizations available in InfluxDB. (Note, this is the same permissions generated for the initial token created by `influx setup` or `influxd upgrade`.) - {{% /oss-only %}} - -### View more buckets in the influx CLI - -Update [`influx bucket list`](/influxdb/cloud/reference/cli/influx/bucket/list/) with pagination to support displaying more than 20 buckets. By default, buckets are fetched in batches of 20; set `--page-size` to override this default value. You may also limit the total number of buckets to display with `--limit` (by default, there's no limit). - -### New bucket shorthand for influx delete - -Add the shorthand flag `-b` for `--bucket` to [`influx delete`](/influxdb/cloud/reference/cli/influx/delete/). - -## Bug fixes - -- Detect and warn when the Operator token is changed using `influx restore` (either setting a new `--active` config or updating the `INFLUX_TOKEN` variable). -- Set newly-created connection configuration as active in `influx setup`. -- Embed timezone data into Windows builds to avoid errors. - -## v2.1.1 [2021-09-24] - -## Go version - -Upgrade to Go 1.17. - -## Bug fixes - -- Fix shell completion for top-level `influx` commands. -- Make global `--http-debug` flag visible in help text. -- Don't set empty strings for IDs in permission resources. -- Detect and error out on incorrect positional arguments. -- Respect value of `--host` flag when writing CLI configs in `setup`. - -## v2.1.0 [2021-07-29] - -## New repository - -This is the initial release of the `influx` CLI from the `influxdata/influx-cli` GitHub repository. - -## Breaking changes - -### `influx write` skip-header parsing - -To simplify the CLI parser, the `write` command no longer supports `--skipHeader` -as short-hand for `--skipHeader 1`. - -### Stricter input validation for `influx template` commands - -The `apply`, `export`, and `stacks` commands now raise errors when CLI options fail to parse instead of silently discarding bad inputs. -This change was made to help users debug when their commands fail to execute as expected. - -### Server-side template summarization and validation - -The `template` and `template validate` commands now use an API request to the server to perform their logic, instead of performing the work on the client-side. -Offline summarization and validation is no longer supported. -This change was made to avoid significant code duplication between `influxdb` and `influx CLI`, and to allow server-side template logic to evolve without requiring coordinated CLI changes. - -### `influx stacks --json` output conventions - -The output of `influx stacks --json` previously used an UpperCamelCase naming convention for most keys. -The command now uses lowerCamelCase consistently for all objects keys, matching the schema returned by the API. - -## Features - -- Add global `--http-debug` flag to all `influx` commands to help inspect communication with InfluxDB servers. -- Update [`bucket create`](/influxdb/cloud/reference/cli/influx/bucket/create/) to allow setting a schema type. -- Update [`bucket list`](/influxdb/cloud/reference/cli/influx/bucket/list/) to display schema types. -- Bind [`--skip-verify`](/influxdb/cloud/reference/cli/influx/org/members/add/#flags) flag to the `INFLUX_SKIP_VERIFY` environment variable. -- (InfluxDB Cloud only) Add [`buck -- (InfluxDB OSS only) Updates to `backup` and `restore`: - - Reimplement [`backup`](/influxdb/cloud/reference/cli/influx/backup/) to support downloading embedded SQL store from InfluxDB 2.0 or later. - - Add [`--compression`](/influxdb/v2.0/reference/cli/influx/backup/_index.md) flag to support GZIP compression of downloaded files. - - Reimplement `restore` to support uploading embedded SQL store from InfluxDB v2.1.x. -- (InfluxDB OSS only) Add [`--password`](/influxdb/cloud/reference/cli/influx/user/password/) flag to `user password` command to allow bypassing interactive prompt. - -## Bug fixes - -- Fix interactive password collection and color rendering in PowerShell. -- `org members list` no longer hangs on organizations with more than 10 members. -- Detect and warn when inputs to `write` contain standalone CR characters. -- `dashboards` command now accepts `--org` flag, or falls back to default org in config. -- Return a consistent error when responses fail to decode, including hints for OSS-only and Cloud-only commands. +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/sign-up.md b/content/influxdb/cloud/sign-up.md index fc1354d9f2..815b8cec22 100644 --- a/content/influxdb/cloud/sign-up.md +++ b/content/influxdb/cloud/sign-up.md @@ -112,7 +112,7 @@ To use the `influx` CLI to manage and interact with your InfluxDB Cloud instance Click the following button to download and install `influx` CLI for macOS. -influx CLI (macOS) +influx CLI (macOS) #### Step 2: Unpackage the influx binary @@ -124,7 +124,7 @@ or run the following command in a macOS command prompt application such ```sh # Unpackage contents to the current working directory -tar zxvf ~/Downloads/influxdb2-client-{{< latest-patch >}}-darwin-amd64.tar.gz +tar zxvf ~/Downloads/influxdb2-client-{{< latest-patch cli=true >}}-darwin-amd64.tar.gz ``` #### Step 3: (Optional) Place the binary in your $PATH @@ -136,7 +136,7 @@ prefix the executable with `./` to run in place. If the binary is on your $PATH, ```sh # Copy the influx binary to your $PATH -sudo cp influxdb2-client-{{< latest-patch >}}-darwin-amd64/influx /usr/local/bin/ +sudo cp influxdb2-client-{{< latest-patch cli=true >}}-darwin-amd64/influx /usr/local/bin/ ``` {{% note %}} @@ -240,7 +240,7 @@ To see all available `influx` commands, type `influx -h` or check out [influx - Click the following button to download and install `influx` CLI for Windows. -influx CLI (Windows) +influx CLI (Windows) #### Step 2: Expand the downloaded archive diff --git a/content/influxdb/cloud/tools/clis.md b/content/influxdb/cloud/tools/clis.md deleted file mode 100644 index bba1dae2ce..0000000000 --- a/content/influxdb/cloud/tools/clis.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Use InfluxDB CLI -description: - Use the `influx` command line interfaces to interact with and manage InfluxDB. -menu: - influxdb_cloud: - parent: Tools & integrations -weight: 102 -influxdb/cloud/tags: [cli] ---- - -Use the `influx` CLI to interact with and manage data in your **InfluxDB** instance. -Write and query data, generate InfluxDB templates, export data, manage organizations -and users, and more. - -_For information about setting up and configuring the `influx` CLI, see [Download, install, and use the influx CLI](/influxdb/cloud/sign-up/#optional-download-install-and-use-the-influx-cli)._ - -_For more information about using the `influx` CLI, see the [`influx` reference documentation](/influxdb/cloud/reference/cli/influx/)._ diff --git a/content/influxdb/cloud/tools/influx-cli.md b/content/influxdb/cloud/tools/influx-cli.md new file mode 100644 index 0000000000..aa2650b03c --- /dev/null +++ b/content/influxdb/cloud/tools/influx-cli.md @@ -0,0 +1,18 @@ +--- +title: Install and use the influx CLI +description: + Use the `influx` command line interface to interact with and manage InfluxDB Cloud. +menu: + influxdb_cloud: + parent: Tools & integrations + name: Use the influx CLI + identifier: influx-cli-task-based +weight: 101 +influxdb/cloud/tags: [cli] +aliases: + - /influxdb/cloud/tools/clis/ +related: + - /influxdb/cloud/reference/cli/influx/ +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/upgrade/v2-to-cloud.md b/content/influxdb/cloud/upgrade/v2-to-cloud.md index bb5aff6635..40508d3fa1 100644 --- a/content/influxdb/cloud/upgrade/v2-to-cloud.md +++ b/content/influxdb/cloud/upgrade/v2-to-cloud.md @@ -25,7 +25,7 @@ To upgrade from **InfluxDB OSS 2.x** to **InfluxDB Cloud**: #### Consider when upgrading - InfluxDB Cloud requires token authentication, and you must create all new API tokens. - InfluxDB Cloud does not support: - - Multiple [organizations](http://localhost:1313/influxdb/cloud/reference/glossary/#organization) per account. + - Multiple [organizations](/influxdb/cloud/reference/glossary/#organization) per account. Upgrade a single InfluxDB OSS 2.x organization to an InfluxDB Cloud organization. To upgrade multiple organizations, create a separate InfluxDB Cloud account for each organization. - [InfluxDB scrapers](/{{< latest "influxdb" >}}/write-data/no-code/scrape-data/). diff --git a/content/influxdb/cloud/visualize-data/visualization-types/band.md b/content/influxdb/cloud/visualize-data/visualization-types/band.md index 7997e2e4aa..18aa146b3d 100644 --- a/content/influxdb/cloud/visualize-data/visualization-types/band.md +++ b/content/influxdb/cloud/visualize-data/visualization-types/band.md @@ -10,165 +10,4 @@ menu: parent: Visualization types --- -The **Band** visualization displays the upper and lower boundaries for groups of data over time. Boundaries are determined by applying aggregate functions to your data for a specified window period, and then setting the aggregate functions for a specified upper, main, or lower boundary. - -## Set up the Band visualization - -To see bands (boundaries) in the **Band Plot** visualization, you must set up two or three boundaries for comparison. - -### Set up the band visualization in the Data Explorer - -1. Click the **Data Explorer** icon in the navigation bar. - - {{< nav-icon "data-explorer" >}} - -2. Enter your query (see [Explore data with Flux and the Data Explorer](/influxdb/v2.0/visualize-data/explore-metrics/#explore-data-with-flux-and-the-data-explorer)). You must include the aggregate functions used to determine the Band Plot visualization boundaries in your query. -3. Select the **Band Plot** option from the visualization dropdown in the upper left, and then click **Customize**. -4. Under **Data**, select the following: - - For **X Column** and **Y Column**, select the columns to display for the x- and y- axes. - - For **Time Format**, select the timestamp format to display in the visualization. -5. Under **Aggregate Functions**, select a function to determine each boundary (column) for comparison (select two or three): - - In the **Upper Column Name** field, select a function for the upper boundary. - - In the **Main Column Name** field, select a function for the main boundary. - - In the **Lower Column Name** field, select a function for the lower boundary. -6. (Optional) Continue to customize your visualization, including options such as interpolation, color, hover dimension, and y-axis settings. For more information, see [Options](#options) and [Y Axis](#y-axis) below. - - **Tip:** If you do not see shaded boundaries in the **Band Plot** visualization, verify the query window period includes a sufficient number of data points for the selected aggregate function. By default, the window period is automatically set to ten seconds (`10s`). To adjust your window period, select **Custom**, and then enter a supported time unit (for example nanoseconds (`ns`), microseconds (`us`), milliseconds (`ms`), seconds (`s`), or hours (`h`). - -{{< img-hd src="/img/influxdb/2-0-visualizations-Band-example.png" alt="Band example" />}} - -### Set up the band plot visualization in the Script Editor - -1. Click the **Data Explorer** icon in the navigation bar. - - {{< nav-icon "data-explorer" >}} - -2. Click **Script Editor**. -3. Select the **Band Plot** option from the visualization dropdown in the upper left. -4. Create three aggregate functions: one for the main boundary, one for the upper boundary, and one for the lower boundary. The following example uses the [`mean()`](/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/aggregates/mean/), [`max()`](/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/selectors/max/), and [`min()`](/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/selectors/min) functions: - -```js -from(bucket: "bucket_1") - |> range(start: v.timeRangeStart, stop: v.timeRangeStop) - |> filter(fn: (r) => r["_measurement"] == "cpu") - |> filter(fn: (r) => r["_field"] == "usage_system") - |> filter(fn: (r) => r["cpu"] == "cpu0" or r["cpu"] == "cpu1") - |> aggregateWindow(every: 15s, fn: mean, createEmpty: false) - |> yield(name: "mean") - -from(bucket: "bucket_1") - |> range(start: v.timeRangeStart, stop: v.timeRangeStop) - |> filter(fn: (r) => r["_measurement"] == "cpu") - |> filter(fn: (r) => r["_field"] == "usage_system") - |> filter(fn: (r) => r["cpu"] == "cpu0" or r["cpu"] == "cpu1") - |> aggregateWindow(every: 15s, fn: max, createEmpty: false) - |> yield(name: "max") - -from(bucket: "bucket_1") - |> range(start: v.timeRangeStart, stop: v.timeRangeStop) - |> filter(fn: (r) => r["_measurement"] == "cpu") - |> filter(fn: (r) => r["_field"] == "usage_system") - |> filter(fn: (r) => r["cpu"] == "cpu0" or r["cpu"] == "cpu1") - |> aggregateWindow(every: 15s, fn: min, createEmpty: false) - |> yield(name: "min") -``` - -5. (Optional) Customize the name of the yielded results for each function by editing the `name` parameter in the [`yield()`](/influxdb/v2.0/reference/flux/stdlib/built-in/outputs/yield/) function. -For example, to change the name of the first function from `mean` to `Average`, modify the last line to the following: - ```js - |> yield(name: "Average") - ``` -6. Click **Customize** in the upper left. -7. Under **Aggregate Functions**, enter the functions you created to determine each boundary (column) for comparison. If you changed the `yield` name for any of the functions above, enter the modified name here instead of the function name: - - In the **Upper Column Name** field, enter the result set to use for the upper boundary. - - In the **Main Column Name** field, enter the result set to use for the main boundary. - - In the **Lower Column Name** field, enter the function for the lower boundary. -7. (Optional) Continue to customize your visualization, including options such as interpolation, color, hover dimension, static legend, and y-axis settings. For more information, see [Options](#options) and [Y Axis](#y-axis) below. - -### Customize column names - -## Band behavior - -Like a line graph, the band visualization shows how values change over time. Additionally, it displays upper and lower "bands" for the measurements. - -For example, in the band chart above, the lines represent the mean `usage_system` values for the `cpu` measurement for `cpu0` and `cpu1`. The upper and lower limits of the bands are defined by the `max` and `min` aggregate functions, respectively. - -## Band controls - -To view **Band** controls, click **{{< icon "gear" >}} Customize** next to the visualization dropdown. - -###### Data - -- **X Column**: Select a column to display on the x-axis. -- **Y Column**: Select a column to display on the y-axis. -- **Time Format**: Select the time format. Options include: - {{< ui/timestamp-formats >}} - -###### Aggregate functions - -- **Upper Column Name**: Aggregate function to display for upper bounds of data. -- **Main Column Name**: Aggregate function to display for main graph line. -- **Lower Column Name**: Aggregate function to display for lower bounds of data. - -###### Options - -- **Interpolation**: - - **Linear**: Display a time series in a line graph. - - **Smooth**: Display a time series in a line graph with smooth point interpolation. - - **Step**: Display a time series in a staircase graph. -- **Line Colors**: Select a color scheme to use for your graph. -- **Hover Dimension**: Select the data to display in the tooltip when you hover over the graph: - - **auto** or **X-Axis**: Show all points with the same x value along the y-axis. - - **Y-Axis**: Show all points with the same y value along the x-axis. - - **X-Y Axis**: Show only the point being currently hovered over. - -###### X-Axis - -- **Generate X-Axis Tick Marks**: Select the method to generate x-axis tick marks: - - **Auto**: Select to automatically generate tick marks. - - **Custom**: To customize the number of x-axis tick marks, select this option, and then enter the following: - - **Total Tick Marks**: Enter the total number of timestamp ticks to display. - - **Start Tick Marks At**: Enter the time, in RFC3339 format, to start displaying ticks. Use the **Date Picker** field to automatically generate an RFC3339 formatted timestamp for this field. - - **Tick Mark Interval**: Enter the number of milliseconds in between each timestamp tick. - -###### Y-Axis - -- **Y Axis Label**: Enter the label for the y-axis. -- **Y-Value Unit Prefix**: Select the prefix to add to the y-value: - - **None**: Select to add no prefix. - - **SI**: (default) Select to add an International System of Units (SI) or metric prefix. - - **Binary**: Select to add a binary multiple prefix. -- **Y Axis Prefix**: Enter the prefix to add to the y-value. -- **Y Axis Suffix**: Enter the suffix to add to the y-value. -- **Generate Y-Axis Tick Marks**: Select the method to generate y-axis tick marks: - - **Auto**: Select to automatically generate tick marks. - - **Custom**: To customize the number of y-axis tick marks, select this option, and then enter the following: - - **Total Tick Marks**: Enter the total number of ticks to display. - - **Start Tick Marks At**: Enter the value to start ticks at. - - **Tick Mark Interval**: Enter the interval in between each tick. -- **Y Axis Domain**: Select the method to generate the y-axis value range: - - **Auto**: Select to automatically determine the value range based on values in the data set. - - **Custom**: To customize the y-axis domain, manually specify the minimum y-axis value, maximum y-axis value, or range by including both. - - **Min**: Enter the minimum y-axis value. - - **Max**: Enter the maximum y-axis value. - - -###### Legend -- **Hover Legend**: - - **Hide**: Hide the legend that appears upon hover. - - **Show**: Show the legend upon hover. - - **Orientation**: Select the orientation of the legend: - - **Horizontal**: Select to display the legend horizontally. - - **Vertical**: Select to display the legend vertically. - - **Opacity**: Adjust the hover legend opacity using the slider. - - **Colorize Rows**: Select to display hover legend rows in colors. -- **Static Legend**: - - **Hide**: Hide the static legend. - - **Show**: Always show the static legend. - - **Orientation**: Select the orientation of the legend: - - **Horizontal**: Select to display the legend horizontally. - - **Vertical**: Select to display the legend vertically. - - **Opacity**: Adjust the static legend opacity using the slider. - - **Colorize Rows**: Select to display static legend rows in colors. - - **Displayed Value**: Select **Latest Y Axis** or **Latest X Axis** to determine whether the y or x axis appears on the legend. - - **Height**: Adjust the height of the static legend using the slider. +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/visualize-data/visualization-types/graph-single-stat.md b/content/influxdb/cloud/visualize-data/visualization-types/graph-single-stat.md index 73b665d1ff..74116f01de 100644 --- a/content/influxdb/cloud/visualize-data/visualization-types/graph-single-stat.md +++ b/content/influxdb/cloud/visualize-data/visualization-types/graph-single-stat.md @@ -15,126 +15,4 @@ related: - /influxdb/v2.0/visualize-data/visualization-types/single-stat --- -The **Graph + Single Stat** view displays the specified time series in a line graph -and overlays the single most recent value as a large numeric value. - -{{< img-hd src="/img/influxdb/2-0-visualizations-line-graph-single-stat-example-8.png" alt="Line Graph + Single Stat example" />}} - -Select the **Graph + Single Stat** option from the visualization dropdown in the upper left. - -## Graph + Single Stat behavior -The Graph visualization color codes each table (or series) in the queried data set. -When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options). - -The Single Stat visualization displays a single numeric data point. -It uses the latest point in the first table (or series) returned by the query. - -{{% note %}} -#### Queries should return one table -Flux does not guarantee the order in which tables are returned. -If a query returns multiple tables (or series), the table order can change between query executions -and result in the Single Stat visualization displaying inconsistent data. -For consistent Single Stat results, the query should return a single table. -{{% /note %}} - -## Graph + Single Stat Controls -To view **Graph + Single Stat** controls, click **{{< icon "gear" >}} Customize** next to -the visualization dropdown. - -###### Data -- **X Column**: Select a column to display on the x-axis. -- **Y Column**: Select a column to display on the y-axis. -- **Time Format**: Select the time format. Options include: - {{< ui/timestamp-formats >}} - -###### Options -- **Line Colors**: Select a color scheme to use for your graph. -- **Shade Area Below Lines**: Shade in the area below the graph lines. -- **Hover Dimension**: Select the data to display in the tooltip when you hover over the graph: - - **auto** or **X Axis**: Show all points with the same x value along the y-axis. - - **Y Axis**: Show all points with the same y value along the x-axis. - - **X & Y Axis**: Show only the point currently being hovered over. - -###### X Axis -- **Generate X-Axis Tick Marks**: Select the method to generate x-axis tick marks: - - **Auto**: Select to automatically generate tick marks. - - **Custom**: To customize the number of x-axis tick marks, select this option, and then enter the following: - - **Total Tick Marks**: Enter the total number of ticks to display. - - **Start Tick Marks At**: Enter the value to start ticks at. - - **Tick Mark Interval**: Enter the interval in between each tick. - -###### Y Axis -- **Y Axis Label**: Label for the y-axis. -- **Y Value Unit Prefix**: - - **None**: No prefix. - - **SI**: International System of Units (SI) or metric prefix. - - **Binary**: Binary multiple prefix. -- **Y Axis Prefix**: Prefix to be added to y-value. -- **Y Axis Suffix**: Suffix to be added to y-value. -- **Generate Y-Axis Tick Marks**: Select the method to generate y-axis tick marks: - - **Auto**: Select to automatically generate tick marks. - - **Custom**: To customize the number of y-axis tick marks, select this option, and then enter the following: - - **Total Tick Marks**: Enter the total number of ticks to display. - - **Start Tick Marks At**: Enter the value to start ticks at. - - **Tick Mark Interval**: Enter the interval in between each tick. -- **Y Axis Domain**: The y-axis value range. - - **Auto**: Automatically determine the value range based on values in the data set. - - **Custom**: Manually specify the minimum y-axis value, maximum y-axis value, or range by including both. - - **Min**: Minimum y-axis value. - - **Max**: Maximum y-axis value. -- **Positioning**: - - **Overlaid**: Display graph lines overlaid on each other. - - **Stacked**: Display graph lines stacked on top of each other. - -###### Customize Single-Stat -- **Prefix**: Prefix to be added to the single stat. -- **Suffix**: Suffix to be added to the single stat. -- **Decimal Places**: The number of decimal places to display for the single stat. - - **Auto** or **Custom**: Enable or disable auto-setting. - -###### Colorized Thresholds -- **Base Color**: Select a base or background color from the selection list. -- **Add a Threshold**: Change the color of the single stat based on the current value. - - **Value is**: Enter the value at which the single stat should appear in the selected color. - Choose a color from the dropdown menu next to the value. -- **Colorization**: Choose **Text** for the single stat to change color based on the configured thresholds. - Choose **Background** for the background of the graph to change color based on the configured thresholds. - -###### Legend -- **Hover Legend**: - - **Hide**: Hide the legend that appears upon hover. - - **Show**: Show the legend upon hover. - - **Orientation**: Select the orientation of the legend: - - **Horizontal**: Select to display the legend horizontally. - - **Vertical**: Select to display the legend vertically. - - **Opacity**: Adjust the hover legend opacity using the slider. - - **Colorize Rows**: Select to display hover legend rows in colors. -- **Static Legend**: - - **Hide**: Hide the static legend. - - **Show**: Always show the static legend. - - **Orientation**: Select the orientation of the legend: - - **Horizontal**: Select to display the legend horizontally. - - **Vertical**: Select to display the legend vertically. - - **Opacity**: Adjust the static legend opacity using the slider. - - **Colorize Rows**: Select to display static legend rows in colors. - - **Displayed Value**: Select **Latest Y Axis** or **Latest X Axis** to determine whether the y or x axis appears on the legend. - - **Height**: Adjust the height of the static legend using the slider. - -## Graph + Single Stat examples -The primary use case for the Graph + Single Stat visualization is to show the current or latest -value as well as historical values. - -### Show current value and historical values -The following example shows the current percentage of memory used as well as memory usage over time: - -###### Query memory usage percentage -```js -from(bucket: "example-bucket") - |> range(start: v.timeRangeStart, stop: v.timeRangeStop) - |> filter(fn: (r) => - r._measurement == "mem" and - r._field == "used_percent" - ) -``` -###### Memory allocations percentage visualization with static legend -{{< img-hd src="/img/influxdb/2-0-visualizations-graph-single-stat-static.png" alt="Graph + Single Stat Memory Usage Example" />}} +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/visualize-data/visualization-types/graph.md b/content/influxdb/cloud/visualize-data/visualization-types/graph.md index 04ca05e7b0..79884d3b06 100644 --- a/content/influxdb/cloud/visualize-data/visualization-types/graph.md +++ b/content/influxdb/cloud/visualize-data/visualization-types/graph.md @@ -11,103 +11,4 @@ menu: parent: Visualization types --- -The Graph visualization provides several types of graphs, each configured through -the [Graph controls](#graph-controls). - -{{< img-hd src="/img/influxdb/2-0-visualizations-line-graph-example-8.png" alt="Line Graph example" />}} - -Select the **Graph** option from the visualization dropdown in the upper left. - -## Graph behavior -The Graph visualization color codes each table (or series) in the queried data set. -When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options). - -When using a line graph, all points within a single table are connected. When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options). - -## Graph controls -To view **Graph** controls, click **{{< icon "gear" >}} Customize** next to -the visualization dropdown. - -###### Data -- **X Column**: Select a column to display on the x-axis. -- **Y Column**: Select a column to display on the y-axis. -- **Time Format**: Select the time format. Options include: - {{< ui/timestamp-formats >}} - -###### Options -- **Interpolation**: Select from the following options: - - **Line**: Display a time series in a line graph - - **Smooth**: Display a time series in a line graph with smooth point interpolation. - - **Step**: Display a time series in a staircase graph. - - -- **Line Colors**: Select a color scheme to use for your graph. -- **Shade Area Below Lines**: Shade in the area below the graph lines. -- **Hover Dimension**: Select the data to display in the tooltip when you hover over the graph: - - **auto** or **X Axis**: Show all points with the same x value along the y-axis. - - **Y Axis**: Show all points with the same y value along the x-axis. - - **X & Y Axis**: Show only the point currently being hovered over. - -###### X Axis -- **Generate X-Axis Tick Marks**: Select the method to generate x-axis tick marks: - - **Auto**: Select to automatically generate tick marks. - - **Custom**: To customize the number of x-axis tick marks, select this option, and then enter the following: - - **Total Tick Marks**: Enter the total number of ticks to display. - - **Start Tick Marks At**: Enter the value to start ticks at. - - **Tick Mark Interval**: Enter the interval in between each tick. - -###### Y Axis -- **Y Axis Label**: Label for the y-axis. -- **Y Axis Prefix**: Prefix to be added to y-value. -- **Y Axis Suffix**: Suffix to be added to y-value. -- **Generate Y-Axis Tick Marks**: Select the method to generate y-axis tick marks: - - **Auto**: Select to automatically generate tick marks. - - **Custom**: To customize the number of y-axis tick marks, select this option, and then enter the following: - - **Total Tick Marks**: Enter the total number of ticks to display. - - **Start Tick Marks At**: Enter the value to start ticks at. - - **Tick Mark Interval**: Enter the interval in between each tick. -- **Y Axis Domain**: The y-axis value range. - - **Auto**: Automatically determine the value range based on values in the data set. - - **Custom**: Manually specify the minimum y-axis value, maximum y-axis value, or range by including both. - - **Min**: Minimum y-axis value. - - **Max**: Maximum y-axis value. -- **Positioning**: - - **Overlaid**: Display graph lines overlaid on each other. - - **Stacked**: Display graph lines stacked on top of each other. - -###### Legend -- **Hover Legend**: - - **Hide**: Hide the legend that appears upon hover. - - **Show**: Show the legend upon hover. - - **Orientation**: Select the orientation of the legend: - - **Horizontal**: Select to display the legend horizontally. - - **Vertical**: Select to display the legend vertically. - - **Opacity**: Adjust the hover legend opacity using the slider. - - **Colorize Rows**: Select to display hover legend rows in colors. -- **Static Legend**: - - **Hide**: Hide the static legend. - - **Show**: Always show the static legend. - - **Orientation**: Select the orientation of the legend: - - **Horizontal**: Select to display the legend horizontally. - - **Vertical**: Select to display the legend vertically. - - **Opacity**: Adjust the static legend opacity using the slider. - - **Colorize Rows**: Select to display static legend rows in colors. - - **Displayed Value**: Select **Latest Y Axis** or **Latest X Axis** to determine whether the y or x axis appears on the legend. - - **Height**: Adjust the height of the static legend using the slider. - -## Graph Examples - -##### Graph with linear interpolation and static legend -{{< img-hd src="/img/influxdb/2-0-visualizations-graph-linear-static.png" alt="Line Graph example" />}} - -##### Graph with smooth interpolation and hover legend -{{< img-hd src="/img/influxdb/2-0-visualizations-graph-smooth-hover.png" alt="Step-Plot Graph example" />}} - -##### Graph with step interpolation and no visible legend -{{< img-hd src="/img/influxdb/2-0-visualizations-line-graph-step-example-8.png" alt="Step-Plot Graph example" />}} - - - - +{{< duplicate-oss >}} diff --git a/content/influxdb/v1.8/query_language/explore-schema.md b/content/influxdb/v1.8/query_language/explore-schema.md index 46c8723ba9..3e49a228e3 100644 --- a/content/influxdb/v1.8/query_language/explore-schema.md +++ b/content/influxdb/v1.8/query_language/explore-schema.md @@ -438,6 +438,11 @@ See the Data Exploration page for documentation on the [`OFFSET` clause](/influxdb/v1.8/query_language/explore-data/#the-offset-clause), and on [Regular expressions in queries](/influxdb/v1.8/query_language/explore-data/#regular-expressions). +The following queries with wildcards characters (`*`) are also allowed: + +- `SHOW MEASUREMENTS ON *.*` to show all databases and all RPs +- `SHOW MEASUREMENTS ON .*` to show a specific database and all its RPs + ### Examples #### Run a `SHOW MEASUREMENTS` query with the `ON` clause diff --git a/content/influxdb/v2.0/influxdb-templates/monitor.md b/content/influxdb/v2.0/influxdb-templates/monitor.md index b7ff1a46c6..4c3079129a 100644 --- a/content/influxdb/v2.0/influxdb-templates/monitor.md +++ b/content/influxdb/v2.0/influxdb-templates/monitor.md @@ -122,7 +122,7 @@ To see your data in real time, view the Monitoring dashboard. 1. Select **Boards** (**Dashboards**) in your **InfluxDB Cloud** account. - {{< nav-icon "dashboards" >}} + {{< nav-icon "dashboards" "v2" >}} 2. Click **InfluxDB OSS Metrics**. Metrics appear in your dashboard. 3. Customize your monitoring dashboard as needed. For example, send an alert in the following cases: @@ -143,11 +143,11 @@ To alert when data stops flowing from InfluxDB OSS instances to your InfluxDB Cl 1. To view the deadman check, click **Alerts** in the navigation bar of your **InfluxDB Cloud** account. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} {{< img-hd src="/img/influxdb/2-0-monitor-oss-deadman.png" />}} 2. Choose a InfluxDB OSS field or create a new OSS field for your deadman alert: - 1. Click **{{< icon "plus" >}} Create** and select **Deadman Check** in the dropown menu. + 1. Click **{{< icon "plus" "v2" >}} Create** and select **Deadman Check** in the dropown menu. 2. Define your query with at least one field. 3. Click **Submit** and **Configure Check**. When metrics stop reporting, you'll receive an alert. @@ -166,7 +166,7 @@ InfluxData supports different endpoints: Slack, PagerDuty, and HTTP. Slack is fr #### Send a notification to Slack 1. Create a [Slack Webhooks](https://api.slack.com/messaging/webhooks). -2. Go to **Alerts > Notification Endpoint** and click **{{< icon "plus" >}} Create**, and enter a name and description for your Slack endpoint. +2. Go to **Alerts > Notification Endpoint** and click **{{< icon "plus" "v2" >}} Create**, and enter a name and description for your Slack endpoint. 3. Enter your Slack Webhook under **Incoming Webhook URL** and click **Create Notification Endpoint**. #### Send a notification to PagerDuty or HTTP @@ -177,5 +177,5 @@ Send a notification to PagerDuty or HTTP endpoints (other webhooks) by [upgradin [Create a notification rule](/influxdb/cloud/monitor-alert/notification-rules/create/) to set rules for when to send a deadman alert message to your notification endpoint. -1. Go to **Alerts > Notification Rules** and click **{{< icon "plus" >}} Create**. +1. Go to **Alerts > Notification Rules** and click **{{< icon "plus" "v2" >}} Create**. 2. Fill out the **About** and **Conditions** section then click **Create Notification Rule**. diff --git a/content/influxdb/v2.0/monitor-alert/checks/create.md b/content/influxdb/v2.0/monitor-alert/checks/create.md index b4f7992903..2a3cffd8ee 100644 --- a/content/influxdb/v2.0/monitor-alert/checks/create.md +++ b/content/influxdb/v2.0/monitor-alert/checks/create.md @@ -45,9 +45,9 @@ in a specified amount of time. ## Create a check in the InfluxDB UI 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} -2. Click **{{< icon "plus" >}} Create** and select the [type of check](#check-types) to create. +2. Click **{{< icon "plus" "v2" >}} Create** and select the [type of check](#check-types) to create. 3. Click **Name this check** in the top left corner and provide a unique name for the check. #### Configure the check query @@ -60,7 +60,7 @@ in a specified amount of time. (for example, "Every 5 minutes") and an aggregate function from the list of functions. 3. Click **Submit** to run the query and preview the results. - To see the raw query results, click the **{{< icon "toggle" >}} View Raw Data** toggle. + To see the raw query results, click the **{{< icon "toggle" "v2" >}} View Raw Data** toggle. #### Configure the check 1. Click **2. Configure Check** near the top of the window. @@ -143,10 +143,10 @@ count = 12 3. In the **And stop checking after** field, enter the time to stop monitoring the series. For example, `30m`, `2h`, `3h15m`, etc. -5. Click the green **{{< icon "check" >}}** in the top right corner to save the check. +5. Click the green **{{< icon "check" "v2" >}}** in the top right corner to save the check. ## Clone a check Create a new check by cloning an existing check. 1. In the **Checks** column, hover over the check you want to clone. -2. Click the **{{< icon "clone" >}}** icon, then **Clone**. +2. Click the **{{< icon "clone" "v2" >}}** icon, then **Clone**. diff --git a/content/influxdb/v2.0/monitor-alert/checks/delete.md b/content/influxdb/v2.0/monitor-alert/checks/delete.md index 2b15d798ed..ebaa57bfa8 100644 --- a/content/influxdb/v2.0/monitor-alert/checks/delete.md +++ b/content/influxdb/v2.0/monitor-alert/checks/delete.md @@ -20,9 +20,9 @@ Deleting a check cannot be undone. 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} -2. Hover over the check you want to delete, click the **{{< icon "delete" >}}** +2. Hover over the check you want to delete, click the **{{< icon "delete" "v2" >}}** icon, and then **Delete**. After a check is deleted, all statuses generated by the check remain in the `_monitoring` diff --git a/content/influxdb/v2.0/monitor-alert/checks/update.md b/content/influxdb/v2.0/monitor-alert/checks/update.md index bab77c246f..9f2fdc6ca5 100644 --- a/content/influxdb/v2.0/monitor-alert/checks/update.md +++ b/content/influxdb/v2.0/monitor-alert/checks/update.md @@ -23,7 +23,7 @@ Common updates include: To update checks, select **Alerts** in the navigation menu on the left. -{{< nav-icon "alerts" >}} +{{< nav-icon "alerts" "v2" >}} ## Update check queries and logic @@ -34,18 +34,18 @@ To update checks, select **Alerts** in the navigation menu on the left. _For details about using the check builder, see [Create checks](/influxdb/v2.0/monitor-alert/checks/create/)._ ## Enable or disable a check -Click the {{< icon "toggle" >}} toggle next to a check to enable or disable it. +Click the {{< icon "toggle" "v2" >}} toggle next to a check to enable or disable it. ## Rename a check 1. Hover over the name of the check you want to update. -2. Click the **{{< icon "edit" >}}** icon that appears next to the check name. +2. Click the **{{< icon "edit" "v2" >}}** icon that appears next to the check name. 2. Enter a new name and click out of the name field or press enter to save. _You can also rename a check in the [check builder](#update-check-queries-and-logic)._ ## Add or update a check description 1. Hover over the check description you want to update. -2. Click the **{{< icon "edit" >}}** icon that appears next to the description. +2. Click the **{{< icon "edit" "v2" >}}** icon that appears next to the description. 2. Enter a new description and click out of the name field or press enter to save. ## Add a label to a check @@ -57,4 +57,4 @@ _You can also rename a check in the [check builder](#update-check-queries-and-lo - In the **Description** field, enter an optional description for the label. - Select a color for the label. - Click **Create Label**. -4. To remove a label, hover over the label under to a rule and click **{{< icon "x" >}}**. +4. To remove a label, hover over the label under to a rule and click **{{< icon "x" "v2" >}}**. diff --git a/content/influxdb/v2.0/monitor-alert/checks/view.md b/content/influxdb/v2.0/monitor-alert/checks/view.md index 451a1adc7d..02af306dc7 100644 --- a/content/influxdb/v2.0/monitor-alert/checks/view.md +++ b/content/influxdb/v2.0/monitor-alert/checks/view.md @@ -21,7 +21,7 @@ View check details and statuses and notifications generated by checks in the Inf To view checks, click **Alerts** in navigation menu on the left. -{{< nav-icon "alerts" >}} +{{< nav-icon "alerts" "v2" >}} ## View a list of all checks The **Checks** section of the Alerts landing page displays all existing checks. @@ -32,12 +32,12 @@ The check builder appears. Here you can view the check query and logic. ## View statuses generated by a check -1. Hover over the check and click the **{{< icon "view" >}}** icon. +1. Hover over the check and click the **{{< icon "view" "v2" >}}** icon. 2. Click **View History**. The Statuses History page displays statuses generated by the selected check. ## View notifications triggered by a check -1. Hover over the check, click the **{{< icon "view" >}}** +1. Hover over the check, click the **{{< icon "view" "v2" >}}** icon, then **View History**. 2. In the top left corner, click **Notifications**. The Notifications History page displays notifications initiated by the selected check. diff --git a/content/influxdb/v2.0/monitor-alert/custom-checks.md b/content/influxdb/v2.0/monitor-alert/custom-checks.md index 5c48dc93b8..b777134ea2 100644 --- a/content/influxdb/v2.0/monitor-alert/custom-checks.md +++ b/content/influxdb/v2.0/monitor-alert/custom-checks.md @@ -23,9 +23,9 @@ Using a Flux task, you can create a custom check that provides a couple advantag 1. In the InfluxDB UI, select **Tasks** in the navigation menu on the left. - {{< nav-icon "tasks" >}} + {{< nav-icon "tasks" "v2" >}} -2. Click **{{< icon "plus" >}} Create Task**, and then select **New Task**. +2. Click **{{< icon "plus" "v2" >}} Create Task**, and then select **New Task**. 3. In the **Name** field, enter a descriptive name, and then enter how often to run the task in the **Every** field (for example, `10m`). For more detail, such as using cron syntax or including an offset, see [Task configuration options](/influxdb/v2.0/process-data/task-options/). diff --git a/content/influxdb/v2.0/monitor-alert/notification-endpoints/create.md b/content/influxdb/v2.0/monitor-alert/notification-endpoints/create.md index ba92a2f0e9..8da605566f 100644 --- a/content/influxdb/v2.0/monitor-alert/notification-endpoints/create.md +++ b/content/influxdb/v2.0/monitor-alert/notification-endpoints/create.md @@ -18,10 +18,10 @@ To send notifications about changes in your data, start by creating a notificati 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} 2. Select **Notification Endpoints** near to top of the page. -3. Click **{{< icon "plus" >}} Create**. +3. Click **{{< icon "plus" "v2" >}} Create**. 4. From the **Destination** drop-down list, select a destination endpoint to send notifications 5. In the **Name** and **Description** fields, enter a name and description for the endpoint. 6. Enter information to connect to the endpoint: diff --git a/content/influxdb/v2.0/monitor-alert/notification-endpoints/delete.md b/content/influxdb/v2.0/monitor-alert/notification-endpoints/delete.md index efb2ed9cf9..3bdb2ae86d 100644 --- a/content/influxdb/v2.0/monitor-alert/notification-endpoints/delete.md +++ b/content/influxdb/v2.0/monitor-alert/notification-endpoints/delete.md @@ -18,9 +18,9 @@ If notifications are no longer sent to an endpoint, complete the steps below to 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} 2. Select **Notification Endpoints** near to top of the page. find the rule you want to delete. -3. Hover over the endpoint you want to delete and click the **{{< icon "trash" >}}** icon. +3. Hover over the endpoint you want to delete and click the **{{< icon "trash" "v2" >}}** icon. 4. Click **Delete** to confirm. diff --git a/content/influxdb/v2.0/monitor-alert/notification-endpoints/update.md b/content/influxdb/v2.0/monitor-alert/notification-endpoints/update.md index 417df79693..cb6b4ee706 100644 --- a/content/influxdb/v2.0/monitor-alert/notification-endpoints/update.md +++ b/content/influxdb/v2.0/monitor-alert/notification-endpoints/update.md @@ -18,10 +18,10 @@ To update the notification endpoint details, complete the procedures below as ne 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} 2. Select **Notification Endpoints** near to top of the page. -3. Click **{{< icon "add-label" >}} Add a label** next to the endpoint you want to add a label to. +3. Click **{{< icon "add-label" "v2" >}} Add a label** next to the endpoint you want to add a label to. The **Add Labels** box opens. 4. To add an existing label, select the label from the list. 5. To create and add a new label: @@ -38,27 +38,27 @@ To update the notification endpoint details, complete the procedures below as ne 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} 2. Select **Notification Endpoints** near to top of the page. -3. Click the {{< icon "toggle" >}} toggle to disable the notification endpoint. +3. Click the {{< icon "toggle" "v2" >}} toggle to disable the notification endpoint. ## Update the name or description for notification endpoint 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} 2. Select **Notification Endpoints** near to top of the page. 3. Hover over the name or description of the endpoint and click the pencil icon - (**{{< icon "edit" >}}**) to edit the field. + (**{{< icon "edit" "v2" >}}**) to edit the field. 4. Click outside of the field to save your changes. ## Change endpoint details 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} 2. Select **Notification Endpoints** near to top of the page. 3. Click the endpoint to update. diff --git a/content/influxdb/v2.0/monitor-alert/notification-endpoints/view.md b/content/influxdb/v2.0/monitor-alert/notification-endpoints/view.md index cda2de2f5e..10e7d8141b 100644 --- a/content/influxdb/v2.0/monitor-alert/notification-endpoints/view.md +++ b/content/influxdb/v2.0/monitor-alert/notification-endpoints/view.md @@ -23,7 +23,7 @@ View notification endpoint details and history in the InfluxDB user interface (U 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} 2. Select **Notification Endpoints** near to top of the page. @@ -31,7 +31,7 @@ View notification endpoint details and history in the InfluxDB user interface (U 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} 2. Select **Notification Endpoints** near to top of the page. 3. Click the name of the notification endpoint you want to view. @@ -41,10 +41,10 @@ View notification endpoint details and history in the InfluxDB user interface (U 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} 2. Select **Notification Endpoints** near to top of the page. -3. Hover over the notification endpoint, click the **{{< icon "view" >}}** icon, then **View History**. +3. Hover over the notification endpoint, click the **{{< icon "view" "v2" >}}** icon, then **View History**. The Check Statuses History page displays: - Statuses generated for the selected notification endpoint diff --git a/content/influxdb/v2.0/monitor-alert/notification-rules/create.md b/content/influxdb/v2.0/monitor-alert/notification-rules/create.md index 5142c16086..0589899e55 100644 --- a/content/influxdb/v2.0/monitor-alert/notification-rules/create.md +++ b/content/influxdb/v2.0/monitor-alert/notification-rules/create.md @@ -19,10 +19,10 @@ _For details, see [Manage checks](/influxdb/v2.0/monitor-alert/checks/) and 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} 2. Select **Notification Rules** near to top of the page. -3. Click **{{< icon "plus" >}} Create**. +3. Click **{{< icon "plus" "v2" >}} Create**. 4. Complete the **About** section: 1. In the **Name** field, enter a name for the notification rule. 2. In the **Schedule Every** field, enter how frequently the rule should run. @@ -37,8 +37,8 @@ _For details, see [Manage checks](/influxdb/v2.0/monitor-alert/checks/) and 1. 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} 2. Select **Notification Rules** near to top of the page. -3. Hover over the rule you want to clone and click the **{{< icon "clone" >}}** icon and select **Clone**. +3. Hover over the rule you want to clone and click the **{{< icon "clone" "v2" >}}** icon and select **Clone**. The cloned rule appears. diff --git a/content/influxdb/v2.0/monitor-alert/notification-rules/delete.md b/content/influxdb/v2.0/monitor-alert/notification-rules/delete.md index 964638e668..d6af220ce6 100644 --- a/content/influxdb/v2.0/monitor-alert/notification-rules/delete.md +++ b/content/influxdb/v2.0/monitor-alert/notification-rules/delete.md @@ -15,8 +15,8 @@ related: 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} 2. Select **Notification Rules** near to top of the page. -3. Hover over the rule you want to delete and click the **{{< icon "trash" >}}** icon. +3. Hover over the rule you want to delete and click the **{{< icon "trash" "v2" >}}** icon. 4. Click **Delete** to confirm. diff --git a/content/influxdb/v2.0/monitor-alert/notification-rules/update.md b/content/influxdb/v2.0/monitor-alert/notification-rules/update.md index ce3fd66d02..55f93046fa 100644 --- a/content/influxdb/v2.0/monitor-alert/notification-rules/update.md +++ b/content/influxdb/v2.0/monitor-alert/notification-rules/update.md @@ -15,10 +15,10 @@ related: 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} 2. Select **Notification Rules** near to top of the page. -3. Click **{{< icon "add-label" >}} Add a label** next to the rule you want to add a label to. +3. Click **{{< icon "add-label" "v2" >}} Add a label** next to the rule you want to add a label to. The **Add Labels** box opens. 4. To add an existing label, select the label from the list. 5. To create and add a new label: @@ -26,25 +26,25 @@ related: - In the **Description** field, enter an optional description for the label. - Select a color for the label. - Click **Create Label**. -6. To remove a label, hover over the label under to a rule and click **{{< icon "x" >}}**. +6. To remove a label, hover over the label under to a rule and click **{{< icon "x" "v2" >}}**. ## Disable notification rules 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} 2. Select **Notification Rules** near to top of the page. -3. Click the {{< icon "toggle" >}} toggle to disable the notification rule. +3. Click the {{< icon "toggle" "v2" >}} toggle to disable the notification rule. ## Update the name or description for notification rules 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} 2. Select **Notification Rules** near to top of the page. 3. Hover over the name or description of a rule and click the pencil icon - (**{{< icon "edit" >}}**) to edit the field. + (**{{< icon "edit" "v2" >}}**) to edit the field. 4. Click outside of the field to save your changes. diff --git a/content/influxdb/v2.0/monitor-alert/notification-rules/view.md b/content/influxdb/v2.0/monitor-alert/notification-rules/view.md index d52530892b..af55560a06 100644 --- a/content/influxdb/v2.0/monitor-alert/notification-rules/view.md +++ b/content/influxdb/v2.0/monitor-alert/notification-rules/view.md @@ -22,7 +22,7 @@ View notification rule details and statuses and notifications generated by notif 1. In the navigation menu on the left, select **Alerts**. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} 2. Select **Notification Rules** near to top of the page. @@ -35,11 +35,11 @@ The check builder appears. Here you can view the check query and logic. ## View statuses generated by a notification rule -Hover over the check, click the **{{< icon "view" >}}** icon, and then **View History**. +Hover over the check, click the **{{< icon "view" "v2" >}}** icon, and then **View History**. The Statuses History page displays statuses generated by the selected check. ## View notifications triggered by a notification rule -1. Hover over the notification rule, click the **{{< icon "view" >}}** +1. Hover over the notification rule, click the **{{< icon "view" "v2" >}}** icon, and then **View History**. 2. In the top left corner, click **Notifications**. The Notifications History page displays notifications initiated by the selected notification rule. diff --git a/content/influxdb/v2.0/monitor-alert/send-email.md b/content/influxdb/v2.0/monitor-alert/send-email.md index fba2dbf8f8..ff46389b2f 100644 --- a/content/influxdb/v2.0/monitor-alert/send-email.md +++ b/content/influxdb/v2.0/monitor-alert/send-email.md @@ -29,9 +29,9 @@ Send an alert email using a third-party service, such as [SendGrid](https://send 1. In the InfluxDB UI, select **Tasks** in the navigation menu on the left. - {{< nav-icon "tasks" >}} + {{< nav-icon "tasks" "v2" >}} -2. Click **{{< icon "plus" >}} Create Task**, and then select **New Task**. +2. Click **{{< icon "plus" "v2" >}} Create Task**, and then select **New Task**. 3. In the **Name** field, enter a descriptive name, for example, **Send alert email**, and then enter how often to run the task in the **Every** field, for example, `10m`. For more detail, such as using cron syntax or including an offset, see [Task configuration options](/influxdb/v2.0/process-data/task-options/). 4. In the right panel, enter the following detail in your **task script** (see [examples below](#examples)): diff --git a/content/influxdb/v2.0/monitor-alert/templates/infrastructure/aws.md b/content/influxdb/v2.0/monitor-alert/templates/infrastructure/aws.md index 552295a212..d7c5beef20 100644 --- a/content/influxdb/v2.0/monitor-alert/templates/infrastructure/aws.md +++ b/content/influxdb/v2.0/monitor-alert/templates/infrastructure/aws.md @@ -53,5 +53,5 @@ The AWS CloudWatch Monitoring template includes the following: 1. In the InfluxDB user interface (UI), select **Boards** (**Dashboards**). - {{< nav-icon "dashboards" >}} + {{< nav-icon "dashboards" "v2" >}} 2. Open your AWS dashboards, and then set the `v.bucket` variable to specify the bucket to query data from (`kubernetes` or `cloudwatch`). diff --git a/content/influxdb/v2.0/monitor-alert/templates/infrastructure/docker.md b/content/influxdb/v2.0/monitor-alert/templates/infrastructure/docker.md index 2f855fbdfa..8a639bb917 100644 --- a/content/influxdb/v2.0/monitor-alert/templates/infrastructure/docker.md +++ b/content/influxdb/v2.0/monitor-alert/templates/infrastructure/docker.md @@ -50,5 +50,5 @@ For more information about how checks, notification endpoints, and notifications 1. In the InfluxDB user interface (UI), select **Boards** (**Dashboards**). - {{< nav-icon "dashboards" >}} + {{< nav-icon "dashboards" "v2" >}} 2. Open the **Docker** dashboard to start monitoring. diff --git a/content/influxdb/v2.0/monitor-alert/templates/infrastructure/vshpere.md b/content/influxdb/v2.0/monitor-alert/templates/infrastructure/vshpere.md index 4f884bd978..e6400d6800 100644 --- a/content/influxdb/v2.0/monitor-alert/templates/infrastructure/vshpere.md +++ b/content/influxdb/v2.0/monitor-alert/templates/infrastructure/vshpere.md @@ -51,5 +51,5 @@ The Docker Monitoring template includes the following: 1. In the InfluxDB user interface (UI), select **Boards** (**Dashboards**). - {{< nav-icon "dashboards" >}} + {{< nav-icon "dashboards" "v2" >}} 2. Open the **vsphere** dashboard to start monitoring. diff --git a/content/influxdb/v2.0/monitor-alert/templates/infrastructure/windows.md b/content/influxdb/v2.0/monitor-alert/templates/infrastructure/windows.md index ca15a86836..2dbe6f60a2 100644 --- a/content/influxdb/v2.0/monitor-alert/templates/infrastructure/windows.md +++ b/content/influxdb/v2.0/monitor-alert/templates/infrastructure/windows.md @@ -44,7 +44,7 @@ The Windows System Monitoring template includes the following: 1. In the InfluxDB user interface (UI), select **Boards** (**Dashboards**). - {{< nav-icon "dashboards" >}} + {{< nav-icon "dashboards" "v2" >}} 2. Open the **Windows System** dashboard to start monitoring. {{% note %}} diff --git a/content/influxdb/v2.0/monitor-alert/templates/networks/haproxy.md b/content/influxdb/v2.0/monitor-alert/templates/networks/haproxy.md index 8b9a7726e1..fb262d3dfe 100644 --- a/content/influxdb/v2.0/monitor-alert/templates/networks/haproxy.md +++ b/content/influxdb/v2.0/monitor-alert/templates/networks/haproxy.md @@ -44,5 +44,5 @@ The HAProxy for InfluxDB v2 template includes the following: 1. In the InfluxDB user interface (UI), select **Boards** (**Dashboards**). - {{< nav-icon "dashboards" >}} + {{< nav-icon "dashboards" "v2" >}} 2. Open the **HAProxy** dashboard to start monitoring. diff --git a/content/influxdb/v2.0/organizations/buckets/create-bucket.md b/content/influxdb/v2.0/organizations/buckets/create-bucket.md index 05482c0924..7a3da094b9 100644 --- a/content/influxdb/v2.0/organizations/buckets/create-bucket.md +++ b/content/influxdb/v2.0/organizations/buckets/create-bucket.md @@ -27,9 +27,9 @@ There are two places you can create a bucket in the UI. 1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. - {{< nav-icon "data" >}} + {{< nav-icon "data" "v2" >}} -2. Click **{{< icon "plus" >}} Create Bucket** in the upper right. +2. Click **{{< icon "plus" "v2" >}} Create Bucket** in the upper right. 3. Enter a **Name** for the bucket. 4. Select when to **Delete Data**: - **Never** to retain data forever. @@ -40,7 +40,7 @@ There are two places you can create a bucket in the UI. 1. In the navigation menu on the left, select **Explore* (**Data Explorer**). - {{< nav-icon "data-explorer" >}} + {{< nav-icon "data-explorer" "v2" >}} 2. In the **From** panel in the Flux Builder, select `+ Create Bucket`. 3. Enter a **Name** for the bucket. diff --git a/content/influxdb/v2.0/organizations/buckets/delete-bucket.md b/content/influxdb/v2.0/organizations/buckets/delete-bucket.md index 66066755c7..2b645542ef 100644 --- a/content/influxdb/v2.0/organizations/buckets/delete-bucket.md +++ b/content/influxdb/v2.0/organizations/buckets/delete-bucket.md @@ -16,10 +16,10 @@ to delete a bucket. 1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. - {{< nav-icon "data" >}} + {{< nav-icon "data" "v2" >}} 2. Hover over the bucket you would like to delete. -3. Click **{{< icon "delete" >}} Delete Bucket** and **Confirm** to delete the bucket. +3. Click **{{< icon "delete" "v2" >}} Delete Bucket** and **Confirm** to delete the bucket. ## Delete a bucket using the influx CLI diff --git a/content/influxdb/v2.0/organizations/buckets/update-bucket.md b/content/influxdb/v2.0/organizations/buckets/update-bucket.md index 5d05399b99..2d3636350c 100644 --- a/content/influxdb/v2.0/organizations/buckets/update-bucket.md +++ b/content/influxdb/v2.0/organizations/buckets/update-bucket.md @@ -25,7 +25,7 @@ If you change a bucket name, be sure to update the bucket in the above places as 1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. - {{< nav-icon "data" >}} + {{< nav-icon "data" "v2" >}} 2. Click **Settings** under the bucket you want to rename. 3. Click **Rename**. @@ -36,7 +36,7 @@ If you change a bucket name, be sure to update the bucket in the above places as 1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. - {{< nav-icon "data" >}} + {{< nav-icon "data" "v2" >}} 2. Click **Settings** next to the bucket you want to update. 3. In the window that appears, edit the bucket's retention period. diff --git a/content/influxdb/v2.0/organizations/buckets/view-buckets.md b/content/influxdb/v2.0/organizations/buckets/view-buckets.md index cfc434ddfb..0a25ee6569 100644 --- a/content/influxdb/v2.0/organizations/buckets/view-buckets.md +++ b/content/influxdb/v2.0/organizations/buckets/view-buckets.md @@ -13,7 +13,7 @@ weight: 202 1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. - {{< nav-icon "data" >}} + {{< nav-icon "data" "v2" >}} A list of buckets with their retention policies and IDs appears. diff --git a/content/influxdb/v2.0/organizations/create-org.md b/content/influxdb/v2.0/organizations/create-org.md index 443ca5f489..878186748f 100644 --- a/content/influxdb/v2.0/organizations/create-org.md +++ b/content/influxdb/v2.0/organizations/create-org.md @@ -26,7 +26,7 @@ Because each organization is created with a bucket, we do not recommend more tha 1. In the navigation menu on the left, click the **Account dropdown**. - {{< nav-icon "account" >}} + {{< nav-icon "account" "v2" >}} 2. Select **Create Organization**. 3. In the window that appears, enter an **Organization Name** and **Bucket Name** and click **Create**. diff --git a/content/influxdb/v2.0/organizations/delete-org.md b/content/influxdb/v2.0/organizations/delete-org.md index 5bb2e65385..483f28f95d 100644 --- a/content/influxdb/v2.0/organizations/delete-org.md +++ b/content/influxdb/v2.0/organizations/delete-org.md @@ -18,7 +18,7 @@ to delete an organization. 1. In the navigation menu on the left, click the **Account dropdown**. - {{< nav-icon "account" >}} + {{< nav-icon "account" "v2" >}} The list of organizations appears. diff --git a/content/influxdb/v2.0/organizations/members/add-member.md b/content/influxdb/v2.0/organizations/members/add-member.md index f3b0b16693..06f69c7b1d 100644 --- a/content/influxdb/v2.0/organizations/members/add-member.md +++ b/content/influxdb/v2.0/organizations/members/add-member.md @@ -15,7 +15,7 @@ Use the `influx` command line interface (CLI) to add a member to an organization 1. In the navigation menu on the left, select **Org (Organization)** > **Members**. - {{< nav-icon "org" >}} + {{< nav-icon "org" "v2" >}} _Complete content coming soon_ --> diff --git a/content/influxdb/v2.0/organizations/members/remove-member.md b/content/influxdb/v2.0/organizations/members/remove-member.md index c9ea391cd7..b9a51cb865 100644 --- a/content/influxdb/v2.0/organizations/members/remove-member.md +++ b/content/influxdb/v2.0/organizations/members/remove-member.md @@ -22,9 +22,9 @@ For information about deleting a user from InfluxDB, see [Delete a user](/influx 1. In the navigation menu on the left, select **Org (Organization)** > **Members**. - {{< nav-icon "org" >}} + {{< nav-icon "org" "v2" >}} -2. Hover over the member you would like to delete and click the **{{< icon "delete" >}}** icon. +2. Hover over the member you would like to delete and click the **{{< icon "delete" "v2" >}}** icon. 3. Click **Delete**. ## Remove a member from an organization using the influx CLI diff --git a/content/influxdb/v2.0/organizations/members/view-members.md b/content/influxdb/v2.0/organizations/members/view-members.md index e2ed2c1aab..2aefcae5bb 100644 --- a/content/influxdb/v2.0/organizations/members/view-members.md +++ b/content/influxdb/v2.0/organizations/members/view-members.md @@ -16,7 +16,7 @@ to view members of an organization. In the navigation menu on the left, select **Org (Organization)** > **Members**. -{{< nav-icon "org" >}} +{{< nav-icon "org" "v2" >}} ## View members of organization using the influx CLI diff --git a/content/influxdb/v2.0/organizations/switch-org.md b/content/influxdb/v2.0/organizations/switch-org.md index 7df24bd066..16e056b3e4 100644 --- a/content/influxdb/v2.0/organizations/switch-org.md +++ b/content/influxdb/v2.0/organizations/switch-org.md @@ -16,7 +16,7 @@ Use the InfluxDB user interface (UI) to switch from one organization to another. 1. In the navigation menu on the left, click the **Account dropdown**. - {{< nav-icon "account" >}} + {{< nav-icon "account" "v2" >}} 2. Select **Switch Organizations**. 3. Click the organization you want to switch to. diff --git a/content/influxdb/v2.0/organizations/update-org.md b/content/influxdb/v2.0/organizations/update-org.md index 5d724e9d26..6a24cc53f1 100644 --- a/content/influxdb/v2.0/organizations/update-org.md +++ b/content/influxdb/v2.0/organizations/update-org.md @@ -27,7 +27,7 @@ If you change an organization name, be sure to update the organization in the ab {{< img-hd src="/img/influxdb/user-icon.png" alt="User Icon" />}} -2. Click **{{< icon "edit" >}} Rename**. A verification window appears. +2. Click **{{< icon "edit" "v2" >}} Rename**. A verification window appears. 3. Review the information, and then click **I understand, let's rename my organization**. 4. Enter a new name for your organization, and then click **Change organization name**. diff --git a/content/influxdb/v2.0/organizations/view-orgs.md b/content/influxdb/v2.0/organizations/view-orgs.md index da39098104..6b52faec79 100644 --- a/content/influxdb/v2.0/organizations/view-orgs.md +++ b/content/influxdb/v2.0/organizations/view-orgs.md @@ -16,7 +16,7 @@ to view organizations. 1. In the navigation menu on the left, click the **Account dropdown**. - {{< nav-icon "account" >}} + {{< nav-icon "account" "v2" >}} 2. Select **Switch Organizations**. The list of organizations appears. diff --git a/content/influxdb/v2.0/process-data/manage-tasks/create-task.md b/content/influxdb/v2.0/process-data/manage-tasks/create-task.md index 5f1fb9eed2..eb0273d2de 100644 --- a/content/influxdb/v2.0/process-data/manage-tasks/create-task.md +++ b/content/influxdb/v2.0/process-data/manage-tasks/create-task.md @@ -33,7 +33,7 @@ The InfluxDB UI provides multiple ways to create a task: ### Create a task from the Data Explorer 1. In the navigation menu on the left, select **Explore** (**Data Explorer**). - {{< nav-icon "data-explorer" >}} + {{< nav-icon "data-explorer" "v2" >}} 2. Build a query and click **Save As** in the upper right. 3. Select the **Task** option. @@ -46,9 +46,9 @@ The InfluxDB UI provides multiple ways to create a task: ### Create a task in the Task UI 1. In the navigation menu on the left, select **Tasks**. - {{< nav-icon "tasks" >}} + {{< nav-icon "tasks" "v2" >}} -2. Click **{{< icon "plus" >}} Create Task** in the upper right. +2. Click **{{< icon "plus" "v2" >}} Create Task** in the upper right. 3. Select **New Task**. 4. In the left panel, specify the task options. See [Task options](/influxdb/v2.0/process-data/task-options) for detailed information about each option. @@ -68,7 +68,7 @@ fields in the left panel when you save the task. ### Import a task 1. In the navigation menu on the left, select **Tasks**. - {{< nav-icon "tasks" >}} + {{< nav-icon "tasks" "v2" >}} 2. Click **+ Create Task** in the upper right. 3. Select **Import Task**. @@ -81,7 +81,7 @@ fields in the left panel when you save the task. ### Create a task from a template 1. In the navigation menu on the left, select **Settings** > **Templates**. - {{< nav-icon "Settings" >}} + {{< nav-icon "Settings" "v2" >}} 2. Select **Templates**. 3. Hover over the template to use to create the task and click **Create**. @@ -90,9 +90,9 @@ fields in the left panel when you save the task. ### Clone a task 1. In the navigation menu on the left, select **Tasks**. - {{< nav-icon "tasks" >}} + {{< nav-icon "tasks" "v2" >}} -2. Hover over the task you would like to clone and click the **{{< icon "duplicate" >}}** icon that appears. +2. Hover over the task you would like to clone and click the **{{< icon "duplicate" "v2" >}}** icon that appears. 4. Click **Clone**. ## Create a task using the influx CLI diff --git a/content/influxdb/v2.0/process-data/manage-tasks/delete-task.md b/content/influxdb/v2.0/process-data/manage-tasks/delete-task.md index f35a28e296..4a2ab12b54 100644 --- a/content/influxdb/v2.0/process-data/manage-tasks/delete-task.md +++ b/content/influxdb/v2.0/process-data/manage-tasks/delete-task.md @@ -15,7 +15,7 @@ related: ## Delete a task in the InfluxDB UI 1. In the navigation menu on the left, select **Tasks**. - {{< nav-icon "tasks" >}} + {{< nav-icon "tasks" "v2" >}} 2. In the list of tasks, hover over the task you would like to delete. 3. Click **Delete** on the far right. diff --git a/content/influxdb/v2.0/process-data/manage-tasks/export-task.md b/content/influxdb/v2.0/process-data/manage-tasks/export-task.md index c176cc13d9..590b97c2cf 100644 --- a/content/influxdb/v2.0/process-data/manage-tasks/export-task.md +++ b/content/influxdb/v2.0/process-data/manage-tasks/export-task.md @@ -15,10 +15,10 @@ Tasks are exported as downloadable JSON files. ## Export a task in the InfluxDB UI 1. In the navigation menu on the left, select **Tasks**. - {{< nav-icon "tasks" >}} + {{< nav-icon "tasks" "v2" >}} 2. In the list of tasks, hover over the task you would like to export and click - the **{{< icon "gear" >}}** icon that appears. + the **{{< icon "gear" "v2" >}}** icon that appears. 3. Select **Export**. 4. Downloading or save the task export file using one of the following options: - Click **Download JSON** to download the exported JSON file. diff --git a/content/influxdb/v2.0/process-data/manage-tasks/run-task.md b/content/influxdb/v2.0/process-data/manage-tasks/run-task.md index 1a45dd7d2b..682a9747f8 100644 --- a/content/influxdb/v2.0/process-data/manage-tasks/run-task.md +++ b/content/influxdb/v2.0/process-data/manage-tasks/run-task.md @@ -21,9 +21,9 @@ however, you can manually run a task from the InfluxDB user interface (UI) or th ## Run a task from the InfluxDB UI 1. In the navigation menu on the left, select **Tasks**. - {{< nav-icon "tasks" >}} + {{< nav-icon "tasks" "v2" >}} -2. Hover over the task you want to run and click the **{{< icon "gear" >}}** icon. +2. Hover over the task you want to run and click the **{{< icon "gear" "v2" >}}** icon. 3. Select **Run Task**. ## Run a task with the influx CLI diff --git a/content/influxdb/v2.0/process-data/manage-tasks/task-run-history.md b/content/influxdb/v2.0/process-data/manage-tasks/task-run-history.md index 5ebfe10ba5..9b3e91422d 100644 --- a/content/influxdb/v2.0/process-data/manage-tasks/task-run-history.md +++ b/content/influxdb/v2.0/process-data/manage-tasks/task-run-history.md @@ -24,9 +24,9 @@ to view task run histories and associated logs. 1. In the navigation menu on the left, select **Tasks**. - {{< nav-icon "tasks" >}} + {{< nav-icon "tasks" "v2" >}} -2. Hover over the task you want to run and click the **{{< icon "gear" >}}** icon. +2. Hover over the task you want to run and click the **{{< icon "gear" "v2" >}}** icon. 3. Select **View Task Runs**. ### View task run logs diff --git a/content/influxdb/v2.0/process-data/manage-tasks/update-task.md b/content/influxdb/v2.0/process-data/manage-tasks/update-task.md index 81480518f0..d934ff1927 100644 --- a/content/influxdb/v2.0/process-data/manage-tasks/update-task.md +++ b/content/influxdb/v2.0/process-data/manage-tasks/update-task.md @@ -15,7 +15,7 @@ related: ## Update a task in the InfluxDB UI Click the **Tasks** icon in the left navigation to view the lists of tasks. -{{< nav-icon "tasks" >}} +{{< nav-icon "tasks" "v2" >}} Click the name of a task to update it. @@ -27,12 +27,12 @@ Click the name of a task to update it. #### Update the status of a task -In the list of tasks, click the {{< icon "toggle" >}} toggle to the left of the +In the list of tasks, click the {{< icon "toggle" "v2" >}} toggle to the left of the task you want to activate or inactivate. #### Update a task description 1. In the list of tasks, hover over the name of the task you want to update. -2. Click the pencil icon {{< icon "pencil" >}}. +2. Click the pencil icon {{< icon "pencil" "v2" >}}. 3. Click outside of the field or press `RETURN` to update. ## Update a task with the influx CLI diff --git a/content/influxdb/v2.0/process-data/manage-tasks/view-tasks.md b/content/influxdb/v2.0/process-data/manage-tasks/view-tasks.md index 22b445cb75..795ded0790 100644 --- a/content/influxdb/v2.0/process-data/manage-tasks/view-tasks.md +++ b/content/influxdb/v2.0/process-data/manage-tasks/view-tasks.md @@ -15,11 +15,11 @@ related: ## View tasks in the InfluxDB UI Click the **Tasks** icon in the left navigation to view the lists of tasks. -{{< nav-icon "tasks" >}} +{{< nav-icon "tasks" "v2" >}} ### Filter the list of tasks -1. Click the **Show Inactive** {{< icon "toggle" >}} toggle to include or exclude +1. Click the **Show Inactive** {{< icon "toggle" "v2" >}} toggle to include or exclude inactive tasks in the list. 2. Enter text in the **Filter tasks** field to search for tasks by name or label. 3. Click the heading of any column to sort by that field. diff --git a/content/influxdb/v2.0/query-data/execute-queries/data-explorer.md b/content/influxdb/v2.0/query-data/execute-queries/data-explorer.md index 7c9bf869bd..effc3fd8bd 100644 --- a/content/influxdb/v2.0/query-data/execute-queries/data-explorer.md +++ b/content/influxdb/v2.0/query-data/execute-queries/data-explorer.md @@ -27,7 +27,7 @@ See [Get started with Flux](/influxdb/v2.0/query-data/get-started) to learn more 1. In the navigation menu on the left, select **Explore** (**Data Explorer**). - {{< nav-icon "data-explorer" >}} + {{< nav-icon "data-explorer" "v2" >}} 2. Use the Flux builder in the bottom panel to create a Flux query: - Select a bucket to define your data source or select `+ Create Bucket` to add a new bucket. @@ -40,7 +40,7 @@ See [Get started with Flux](/influxdb/v2.0/query-data/get-started) to learn more Click a function from the list to add it to your query. 5. Click **Submit** (or press `Control+Enter`) to run your query. You can then preview your graph in the above pane. To cancel your query while it's running, click **Cancel**. -6. To work on multiple queries at once, click the {{< icon "plus" >}} to add another tab. +6. To work on multiple queries at once, click the {{< icon "plus" "v2" >}} to add another tab. * Click the eye icon on a tab to hide or show a query's visualization. * Click the name of the query in the tab to rename it. @@ -57,7 +57,7 @@ To open the cell editor overlay, click the gear icon in the upper right of a cel ### View raw data -Toggle the **View Raw Data** {{< icon "toggle" >}} option to see your data in table format instead of a graph. Scroll through raw data using arrows, or click page numbers to find specific tables. [Group keys](/influxdb/cloud/reference/glossary/#group-key) and [data types](/influxdb/cloud/reference/glossary/#data-type) are easily identifiable at the top of each column underneath the headings. Use this option when data can't be visualized using a visualization type. +Toggle the **View Raw Data** {{< icon "toggle" "v2" >}} option to see your data in table format instead of a graph. Scroll through raw data using arrows, or click page numbers to find specific tables. [Group keys](/influxdb/cloud/reference/glossary/#group-key) and [data types](/influxdb/cloud/reference/glossary/#data-type) are easily identifiable at the top of each column underneath the headings. Use this option when data can't be visualized using a visualization type. {{< img-hd src="/img/influxdb/cloud-controls-view-raw-data.png" alt="View raw data" />}} @@ -67,7 +67,7 @@ Click the CSV icon to save the cells contents as a CSV file. ### Manually refresh dashboard -Click the refresh button ({{< icon "refresh" >}}) to manually refresh the dashboard's data. +Click the refresh button ({{< icon "refresh" "v2" >}}) to manually refresh the dashboard's data. ### Select time range diff --git a/content/influxdb/v2.0/query-data/execute-queries/query-sample-data.md b/content/influxdb/v2.0/query-data/execute-queries/query-sample-data.md index 2b7757bcce..c6d552faf9 100644 --- a/content/influxdb/v2.0/query-data/execute-queries/query-sample-data.md +++ b/content/influxdb/v2.0/query-data/execute-queries/query-sample-data.md @@ -42,7 +42,7 @@ If you also want to explore Cloud, we offer a way to explore data without incurr 1. Visit the **InfluxDB templates page** in the InfluxDB OSS UI. Click **Settings** > **Templates** in the navigation menu on the left. - {{< nav-icon "settings" >}} + {{< nav-icon "settings" "v2" >}} 2. Paste the Sample Data community temple URL in **resource manifest file** field: @@ -56,15 +56,15 @@ to query and visualize data in sample data buckets. In the navigation menu on the left, click **Explore (Data Explorer)**. -{{< nav-icon "explore" >}} +{{< nav-icon "explore" "v2" >}} ### Add sample data 1. In the navigation menu on the left, click **Data (Load Data)** > **Buckets**. - {{< nav-icon "data" >}} + {{< nav-icon "data" "v2" >}} -2. Click **{{< icon "plus" >}} Create bucket**, and then name your bucket. The bucket will appear in your list of buckets. +2. Click **{{< icon "plus" "v2" >}} Create bucket**, and then name your bucket. The bucket will appear in your list of buckets. 3. View the [sample datasets document](/influxdb/cloud/reference/sample-data/#sample-datasets) and choose a sample data to query. 4. Copy the `sample.data()` function listed underneath. 5. Click **Explore** on the left navigation of InfluxDB Cloud and click your bucket, and then click **Script Editor**. @@ -79,7 +79,7 @@ After adding a sample data bucket, create a dashboard specific to the sample dat 1. Click **Boards (Dashboards)** in the navigation menu on the left. - {{< nav-icon "dashboards" >}} + {{< nav-icon "dashboards" "v2" >}} 2. Click **Create Dashboard > New Dashboard**, and name the dashboard after your bucket. 3. Click **Add Cell**, and select your sample data bucket. diff --git a/content/influxdb/v2.0/query-data/flux/monitor-states.md b/content/influxdb/v2.0/query-data/flux/monitor-states.md index b75d777c5c..a4523ca68f 100644 --- a/content/influxdb/v2.0/query-data/flux/monitor-states.md +++ b/content/influxdb/v2.0/query-data/flux/monitor-states.md @@ -152,7 +152,7 @@ Detect state changes with the `monitor.stateChanges()` function. To use the `mon 1. In the InfluxDB user interface, click the **Monitoring and Alerting** icon from the sidebar. - {{< nav-icon "alerts" >}} + {{< nav-icon "alerts" "v2" >}} 2. If you haven't already, [create a check](/influxdb/v2.0/monitor-alert/checks/create/) that stores statuses (`CRIT`, `WARN`, `INFO`, `OK` or `ANY`) in the `_level` column. +{{< cli/influxd-flags >}} diff --git a/content/influxdb/v2.0/reference/config-options.md b/content/influxdb/v2.0/reference/config-options.md index b8e5ad7d89..8b8f6f2aad 100644 --- a/content/influxdb/v2.0/reference/config-options.md +++ b/content/influxdb/v2.0/reference/config-options.md @@ -96,6 +96,7 @@ To configure InfluxDB, use the following configuration options when starting the - [bolt-path](#bolt-path) - [e2e-testing](#e2e-testing) - [engine-path](#engine-path) +- [feature-flags](#feature-flags) - [flux-log-enabled](#flux-log-enabled) - [http-bind-address](#http-bind-address) - [http-idle-timeout](#http-idle-timeout) @@ -142,6 +143,7 @@ To configure InfluxDB, use the following configuration options when starting the - [tls-min-version](#tls-min-version) - [tls-strict-ciphers](#tls-strict-ciphers) - [tracing-type](#tracing-type) +- [ui-disabled](#ui-disabled) - [vault-addr](#vault-addr) - [vault-cacert](#vault-cacert) - [vault-capath](#vault-capath) @@ -232,18 +234,18 @@ export INFLUXD_BOLT_PATH=~/.influxdbv2/influxd.bolt {{% /code-tabs %}} {{% code-tab-content %}} ```yml -bolt-path: /users/user/.influxdbv2/influxd.bolt +bolt-path: ~/.influxdbv2/influxd.bolt ``` {{% /code-tab-content %}} {{% code-tab-content %}} ```toml -bolt-path = "/users/user/.influxdbv2/influxd.bolt" +bolt-path = "~/.influxdbv2/influxd.bolt" ``` {{% /code-tab-content %}} {{% code-tab-content %}} ```json { - "bolt-path": "/users/user/.influxdbv2/influxd.bolt" + "bolt-path": "~/.influxdbv2/influxd.bolt" } ``` {{% /code-tab-content %}} @@ -326,18 +328,75 @@ export INFLUXD_ENGINE_PATH=~/.influxdbv2/engine {{% /code-tabs %}} {{% code-tab-content %}} ```yml -engine-path: /users/user/.influxdbv2/engine +engine-path: ~/.influxdbv2/engine ``` {{% /code-tab-content %}} {{% code-tab-content %}} ```toml -engine-path = "/users/user/.influxdbv2/engine" +engine-path = "~/.influxdbv2/engine" ``` {{% /code-tab-content %}} {{% code-tab-content %}} ```json { - "engine-path": "/users/user/.influxdbv2/engine" + "engine-path": "~/.influxdbv2/engine" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### feature-flags +Enable, disable, or override default values for feature flags. + +{{% note %}} +Feature flags are used to develop and test experimental features and are +intended for internal use only. +{{% /note %}} + +| influxd flag | Environment variable | Configuration key | +| :---------------- | :---------------------- | :---------------- | +| `--feature-flags` | `INFLUXD_FEATURE_FLAGS` | `feature-flags` | + +###### influxd flag +```sh +influxd --feature-flags flag1=value2,flag2=value2 +``` + +###### Environment variable +```sh +export INFLUXD_FEATURE_FLAGS="{\"flag1\":\value1\",\"flag2\":\"value2\"}" +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +feature-flags: + flag1: "value1" + flag2: "value2" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +[feature-flags] + flag1 = "value1" + glag2 = "value2" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "feature-flags": { + "flag1": "value1", + "flag2": "value2" + } } ``` {{% /code-tab-content %}} @@ -1527,58 +1586,6 @@ session-renew-disabled = true --- - - - ### storage-cache-max-memory-size Maximum size (in bytes) a shard's cache can reach before it starts rejecting writes. @@ -2308,8 +2315,13 @@ storage-wal-fsync-delay = "0s" ### store Specifies the data store for REST resources. -**Options:** `bolt`, `memory` -**Default:** `bolt` +**Options:** `disk`, `memory` +**Default:** `disk` + +{{% note %}} +For backwards compatibility, this flag also acceptss `bolt` as a value. +When using `disk`, REST resources are stored on disk using the [bolt-path](#bolt-path) and [sqlite-path](#sqlite-path). +{{% /note %}} {{% note %}} `memory` is meant for transient environments, such as testing environments, where @@ -2411,7 +2423,7 @@ testing-always-allow-setup = true Path to TLS certificate file. Requires the [`tls-key`](#tls-key) to be set. -_For more information, see [Enable TLS encryption](/influxdb/v2.0/security/enable-tls/)._ +_For more information, see [Enable TLS encryption](/influxdb/v2.1/security/enable-tls/)._ | influxd flag | Environment variable | Configuration key | |:------------ |:-------------------- |:----------------- | @@ -2459,7 +2471,7 @@ tls-cert = "/path/to/influxdb.crt" Path to TLS key file. Requires the [`tls-cert`](#tls-cert) to be set. -_For more information, see [Enable TLS encryption](/influxdb/v2.0/security/enable-tls/)._ +_For more information, see [Enable TLS encryption](/influxdb/v2.1/security/enable-tls/)._ | influxd flag | Environment variable | Configuration key | |:------------ |:-------------------- |:----------------- | @@ -2650,6 +2662,55 @@ tracing-type = "log" --- +### ui-disabled +Disable the InfluxDB user interface (UI). +The UI is enabled by default. + +**Default:** `false` + +| influxd flag | Environment variable | Configuration key | +| :-------------- | :-------------------- | :---------------- | +| `--ui-disabled` | `INFLUXD_UI_DISABLED` | `ui-disabled` | + +###### influxd flag +```sh +influxd --ui-disabled +``` + +###### Environment variable +```sh +export INFLUXD_UI_DISABLED=true +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +ui-disabled: true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +ui-disabled = true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "ui-disabled": true +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + + ### vault-addr Specifies the address of the Vault server expressed as a URL and port. For example: `https://127.0.0.1:8200/`. diff --git a/content/influxdb/v2.0/security/tokens/create-token.md b/content/influxdb/v2.0/security/tokens/create-token.md index 3970187867..cbc87846bd 100644 --- a/content/influxdb/v2.0/security/tokens/create-token.md +++ b/content/influxdb/v2.0/security/tokens/create-token.md @@ -23,9 +23,9 @@ Tokens are visible to the user who created the token. {{% oss-only %}} Users who 1. In the navigation menu on the left, select **Data (Load Data)** > **Tokens**. - {{< nav-icon "disks" >}} + {{< nav-icon "disks" "v2" >}} -2. Click **{{< icon "plus" >}} Generate** and select a token type +2. Click **{{< icon "plus" "v2" >}} Generate** and select a token type (**Read/Write Token** or **All-Access Token**). 3. In the window that appears, enter a description for your token in the **Description** field. 4. If generating a **read/write token**: diff --git a/content/influxdb/v2.0/security/tokens/delete-token.md b/content/influxdb/v2.0/security/tokens/delete-token.md index b96fe4633c..cfddd2cec7 100644 --- a/content/influxdb/v2.0/security/tokens/delete-token.md +++ b/content/influxdb/v2.0/security/tokens/delete-token.md @@ -19,7 +19,7 @@ have access to your InfluxDB instance. 1. In the navigation menu on the left, select **Data (Load Data)** > **Tokens**. - {{< nav-icon "disks" >}} + {{< nav-icon "disks" "v2" >}} 2. Hover over the token you want to delete and click **Delete** and **Confirm**. diff --git a/content/influxdb/v2.0/security/tokens/update-tokens.md b/content/influxdb/v2.0/security/tokens/update-tokens.md index dbca462f00..21b51c1a5b 100644 --- a/content/influxdb/v2.0/security/tokens/update-tokens.md +++ b/content/influxdb/v2.0/security/tokens/update-tokens.md @@ -17,15 +17,15 @@ Update an API token's description using the InfluxDB user interface (UI). 1. In the navigation menu on the left, select **Data (Load Data)** > **Tokens**. - {{< nav-icon "disks" >}} + {{< nav-icon "disks" "v2" >}} -2. Click the pencil icon {{< icon "pencil" >}} next to the token's name in the **Description** column. +2. Click the pencil icon {{< icon "pencil" "v2" >}} next to the token's name in the **Description** column. 3. Update the token description, then click anywhere else to save. ## Enable or disable a token 1. In the navigation menu on the left, select **Data (Load Data)** > **Tokens**. - {{< nav-icon "disks" >}} + {{< nav-icon "disks" "v2" >}} -2. Click the **{{< icon "toggle-green" >}} Status** toggle. +2. Click the **{{< icon "toggle-green" "v2" >}} Status** toggle. diff --git a/content/influxdb/v2.0/security/tokens/view-tokens.md b/content/influxdb/v2.0/security/tokens/view-tokens.md index cd785979c3..b4ebae595d 100644 --- a/content/influxdb/v2.0/security/tokens/view-tokens.md +++ b/content/influxdb/v2.0/security/tokens/view-tokens.md @@ -23,7 +23,7 @@ Tokens are visible to the user who created the token. {{% oss-only %}} Users who 1. In the navigation menu on the left, select **Data (Load Data)** > **Tokens**. - {{< nav-icon "disks" >}} + {{< nav-icon "disks" "v2" >}} 2. Click a token name from the list to view the token and a summary of access permissions. diff --git a/content/influxdb/v2.0/telegraf-configs/clone.md b/content/influxdb/v2.0/telegraf-configs/clone.md index 5d9a570288..5557380c11 100644 --- a/content/influxdb/v2.0/telegraf-configs/clone.md +++ b/content/influxdb/v2.0/telegraf-configs/clone.md @@ -16,6 +16,6 @@ Use the InfluxDB user interface (UI) to clone a Telegraf configuration. {{< nav-icon "load data" >}} -2. Hover over the configuration you want to clone, click the **{{< icon "clone" >}}** +2. Hover over the configuration you want to clone, click the **{{< icon "clone" "v2" >}}** icon, and then click **Clone**. The clone appears in your list of Telegraf configurations. diff --git a/content/influxdb/v2.0/telegraf-configs/remove.md b/content/influxdb/v2.0/telegraf-configs/remove.md index da210a8843..3b9f8cfd82 100644 --- a/content/influxdb/v2.0/telegraf-configs/remove.md +++ b/content/influxdb/v2.0/telegraf-configs/remove.md @@ -32,7 +32,7 @@ To remove a Telegraf configuration, do one of the following: {{< nav-icon "load data" >}} -2. Hover over the configuration you want to delete, click the **{{< icon "trash" >}}** +2. Hover over the configuration you want to delete, click the **{{< icon "trash" "v2" >}}** icon, and then click **Delete**. diff --git a/content/influxdb/v2.0/telegraf-configs/update.md b/content/influxdb/v2.0/telegraf-configs/update.md index ec4cf65d74..76eae7ed89 100644 --- a/content/influxdb/v2.0/telegraf-configs/update.md +++ b/content/influxdb/v2.0/telegraf-configs/update.md @@ -33,7 +33,7 @@ Telegraf doesn't detect changes to remote configurations. If you edit a remote c {{< nav-icon "load data" >}} -2. Hover over the configuration you want to edit and click **{{< icon "pencil" >}}** +2. Hover over the configuration you want to edit and click **{{< icon "pencil" "v2" >}}** to update the name or description. 3. Press **Return** or click out of the editable field to save your changes. diff --git a/content/influxdb/v2.0/tools/chronograf.md b/content/influxdb/v2.0/tools/chronograf.md index 3f71cd3755..092ca96e2e 100644 --- a/content/influxdb/v2.0/tools/chronograf.md +++ b/content/influxdb/v2.0/tools/chronograf.md @@ -22,7 +22,7 @@ Continue to use Chronograf with **InfluxDB Cloud** and **InfluxDB OSS 2.0** and ## Create an InfluxDB connection 1. In Choronograf, click **Configuration** in the left navigation bar, - and then click **{{< icon "plus" >}} Add Connection**. + and then click **{{< icon "plus" "v2" >}} Add Connection**. 2. Toggle the **InfluxDB v2 Auth** option at the bottom of the form. {{< img-hd src="/img/influxdb/2-0-tools-chronograf-v2-auth.png" alt="InfluxDB v2 Auth toggle" />}} @@ -83,7 +83,7 @@ For example, you **cannot** do the following: - Kill queries When connected to an InfluxDB Cloud or InfluxDB 2.0 database, functionality in the -**{{< icon "crown" >}} InfluxDB Admin** section of Chronograf is disabled. +**{{< icon "crown" "v2" >}} InfluxDB Admin** section of Chronograf is disabled. To complete administrative tasks, use the following: diff --git a/content/influxdb/v2.0/visualize-data/dashboards/control-dashboard.md b/content/influxdb/v2.0/visualize-data/dashboards/control-dashboard.md index 39147e67ae..0af1ee26b4 100644 --- a/content/influxdb/v2.0/visualize-data/dashboards/control-dashboard.md +++ b/content/influxdb/v2.0/visualize-data/dashboards/control-dashboard.md @@ -16,13 +16,13 @@ Use dashboard controls in the upper left to update your dashboard. ### Add a cell -Click **{{< icon "add-cell" >}} Add Cell** to open the Data Explorer and configure a new cell for your dashboard. +Click **{{< icon "add-cell" "v2" >}} Add Cell** to open the Data Explorer and configure a new cell for your dashboard. For details on using the Data Explorer, see [Explore metrics](/influxdb/v2.0/visualize-data/explore-metrics/). ### Add a note -1. Click **{{< icon "note" >}} Add Note** to add a note cell to your dashboard. +1. Click **{{< icon "note" "v2" >}} Add Note** to add a note cell to your dashboard. 2. Enter your note in Markdown in the left pane. A preview appears in the right pane. 3. Enable the **Show note when query returns no data** option to show the note only when the query displays no data. 4. Click **Save**. @@ -35,12 +35,12 @@ Click the timezone dropdown to select a timezone to use for the dashboard. Selec ### Manually refresh dashboard -Click the refresh button (**{{< icon "refresh" >}}**) to manually refresh the dashboard's data. +Click the refresh button (**{{< icon "refresh" "v2" >}}**) to manually refresh the dashboard's data. #### Manually refresh a single dashboard cell -1. Click the **{{< icon "gear" >}}** on the dashboard cell you want to refresh. -2. Click **{{< icon "refresh" >}} Refresh**. +1. Click the **{{< icon "gear" "v2" >}}** on the dashboard cell you want to refresh. +2. Click **{{< icon "refresh" "v2" >}} Refresh**. ### Select time range @@ -59,7 +59,7 @@ Click **Variables** to display variables available for your dashboard. For detai ### Presentation mode -Click the fullscreen icon (**{{< icon "fullscreen" >}}**) to enter presentation mode. Presentation mode allows you to view [a dashboard] in full screen, hiding the left and top navigation menus so only the cells appear. This mode might be helpful, for example, for stationary screens dedicated to monitoring visualizations. +Click the fullscreen icon (**{{< icon "fullscreen" "v2" >}}**) to enter presentation mode. Presentation mode allows you to view [a dashboard] in full screen, hiding the left and top navigation menus so only the cells appear. This mode might be helpful, for example, for stationary screens dedicated to monitoring visualizations. ### Toggle dark mode and light mode Click the moon or sun icons to toggle your dashboard between **dark mode** and **light mode.** diff --git a/content/influxdb/v2.0/visualize-data/dashboards/create-dashboard.md b/content/influxdb/v2.0/visualize-data/dashboards/create-dashboard.md index 150d903bf6..7588532d24 100644 --- a/content/influxdb/v2.0/visualize-data/dashboards/create-dashboard.md +++ b/content/influxdb/v2.0/visualize-data/dashboards/create-dashboard.md @@ -16,9 +16,9 @@ weight: 201 1. In the navigation menu on the left, select **Boards** (**Dashboards**). - {{< nav-icon "dashboards" >}} + {{< nav-icon "dashboards" "v2" >}} -2. Click the **{{< icon "plus" >}} Create Dashboard** menu in the upper right and select **New Dashboard**. +2. Click the **{{< icon "plus" "v2" >}} Create Dashboard** menu in the upper right and select **New Dashboard**. 3. Enter a name for your dashboard in the **Name this dashboard** field in the upper left. @@ -26,7 +26,7 @@ weight: 201 1. In the navigation menu on the left, select **Boards** (**Dashboards**). - {{< nav-icon "dashboards" >}} + {{< nav-icon "dashboards" "v2" >}} 2. Click the **Create Dashboard** menu in the upper right and select **Import Dashboard**. 3. In the window that appears: @@ -38,21 +38,21 @@ weight: 201 1. In the navigation menu on the left, select **Boards** (**Dashboards**). - {{< nav-icon "dashboards" >}} + {{< nav-icon "dashboards" "v2" >}} -2. Hover over the dashboard and click **{{< icon "copy" >}}**. +2. Hover over the dashboard and click **{{< icon "copy" "v2" >}}**. 3. Click **Clone**. The cloned dashboard opens. #### Add data to your dashboard -1. From your dashboard, click **{{< icon "add-cell" >}} Add Cell**. +1. From your dashboard, click **{{< icon "add-cell" "v2" >}} Add Cell**. 2. Create a query in the Data Explorer following the instructions in [Explore metrics](/influxdb/v2.0/visualize-data/explore-metrics). 3. Enter a name for your cell in the upper left. -4. Click the checkmark icon (**{{< icon "checkmark" >}}**) to save the cell to your dashboard. +4. Click the checkmark icon (**{{< icon "checkmark" "v2" >}}**) to save the cell to your dashboard. You can also send data to your dashboard directly from the Data Explorer. For details, [Explore metrics](/influxdb/v2.0/visualize-data/explore-metrics). #### Add a note to your dashboard -1. From your dashboard, click **{{< icon "note" >}} Add Note** in the upper left. +1. From your dashboard, click **{{< icon "note" "v2" >}} Add Note** in the upper left. 2. Enter your note in the window that appears. You can use Markdown syntax to format your note. 3. To preview your Markdown formatting, click the **Preview** option. 4. Click **Save**. diff --git a/content/influxdb/v2.0/visualize-data/dashboards/delete-dashboard.md b/content/influxdb/v2.0/visualize-data/dashboards/delete-dashboard.md index 31a2fdcf5b..f2ac79ceef 100644 --- a/content/influxdb/v2.0/visualize-data/dashboards/delete-dashboard.md +++ b/content/influxdb/v2.0/visualize-data/dashboards/delete-dashboard.md @@ -13,9 +13,9 @@ To delete a dashboard from the InfluxDB user interface (UI): 1. In the navigation menu on the left, select **Boards** (**Dashboards**). - {{< nav-icon "dashboards" >}} + {{< nav-icon "dashboards" "v2" >}} -2. Hover over the dashboard in the list of dashboards and click **{{< icon "trash" >}}**. +2. Hover over the dashboard in the list of dashboards and click **{{< icon "trash" "v2" >}}**. 3. Click **Delete**. {{% warn %}} diff --git a/content/influxdb/v2.0/visualize-data/dashboards/export-dashboard.md b/content/influxdb/v2.0/visualize-data/dashboards/export-dashboard.md index 70ed1e76bd..d7b583b13d 100644 --- a/content/influxdb/v2.0/visualize-data/dashboards/export-dashboard.md +++ b/content/influxdb/v2.0/visualize-data/dashboards/export-dashboard.md @@ -15,9 +15,9 @@ InfluxDB lets you export dashboards from the InfluxDB user interface (UI). 1. In the navigation menu on the left, select **Boards** (**Dashboards**). - {{< nav-icon "dashboards" >}} + {{< nav-icon "dashboards" "v2" >}} -2. Hover over a dashboard and click the gear icon (**{{< icon "gear" >}}**), +2. Hover over a dashboard and click the gear icon (**{{< icon "gear" "v2" >}}**), and then select **Export**. 3. Review the JSON in the window that appears. 4. Select one of the following options: diff --git a/content/influxdb/v2.0/visualize-data/labels.md b/content/influxdb/v2.0/visualize-data/labels.md index ad61b14e4c..83c37b0ffe 100644 --- a/content/influxdb/v2.0/visualize-data/labels.md +++ b/content/influxdb/v2.0/visualize-data/labels.md @@ -16,11 +16,11 @@ To manage labels: - In the navigation menu on the left, select **Settings** > **Labels**. - {{< nav-icon "settings" >}} + {{< nav-icon "settings" "v2" >}} #### Create a label -1. Click **{{< icon "plus" >}} Create Label**. +1. Click **{{< icon "plus" "v2" >}} Create Label**. 2. Enter a **Name** for the label. 3. Enter a description for the label _(Optional)_. 4. Select a **Color** for the label. @@ -33,12 +33,12 @@ To manage labels: 3. Click **Save Changes**. #### Delete a label -1. In the label list view, hover over the label you would like to delete and click **{{< icon "trash" >}}**. +1. In the label list view, hover over the label you would like to delete and click **{{< icon "trash" "v2" >}}**. 2. Click **Delete**. ### Add labels to dashboard items 1. In the list view of dashboards, tasks, or other assets, hover over the item to which you would like to add a label. -2. Click the {{< icon "add-label" >}} icon that appears below the name. +2. Click the {{< icon "add-label" "v2" >}} icon that appears below the name. The **Add Labels** overlay will appear. 3. Type the name of the label you would like to add to filter the list of available labels. Click the label you would like to add. diff --git a/content/influxdb/v2.0/visualize-data/variables/create-variable.md b/content/influxdb/v2.0/visualize-data/variables/create-variable.md index 82e9bb4c17..f0242a0cee 100644 --- a/content/influxdb/v2.0/visualize-data/variables/create-variable.md +++ b/content/influxdb/v2.0/visualize-data/variables/create-variable.md @@ -34,7 +34,7 @@ The [Table visualization type](/influxdb/v2.0/visualize-data/visualization-types 1. Click the **Data Explorer** icon in the sidebar. - {{< nav-icon "data-explorer" >}} + {{< nav-icon "data-explorer" "v2" >}} 2. Use the **Query Builder** or **Script Editor** to build a query. 3. Use the [Table visualization type](/influxdb/v2.0/visualize-data/visualization-types/table/) @@ -50,7 +50,7 @@ _For information about common Query variables, see [Common variable queries](/in 1. Click the **Settings** icon in the navigation bar. - {{< nav-icon "settings" >}} + {{< nav-icon "settings" "v2" >}} 2. Select the **Variables** tab. 3. Enter a name for your variable. @@ -63,10 +63,10 @@ InfluxDB lets you import variables exported from InfluxDB in JSON format. 1. Click the **Settings** icon in the navigation bar. - {{< nav-icon "settings" >}} + {{< nav-icon "settings" "v2" >}} 2. Select the **Variables** tab. -3. Click the **{{< icon "plus" >}} Create Variable** drop-down menu and select **Import Variable**. +3. Click the **{{< icon "plus" "v2" >}} Create Variable** drop-down menu and select **Import Variable**. 4. In the window that appears: - Select **Upload File** to drag and drop or select a file. - Select **Paste JSON** to paste in JSON. diff --git a/content/influxdb/v2.0/visualize-data/variables/delete-variable.md b/content/influxdb/v2.0/visualize-data/variables/delete-variable.md index 4d8fea5dda..30913dca3f 100644 --- a/content/influxdb/v2.0/visualize-data/variables/delete-variable.md +++ b/content/influxdb/v2.0/visualize-data/variables/delete-variable.md @@ -15,10 +15,10 @@ Delete an existing variable in the InfluxDB user interface (UI). 1. Click the **Settings** icon in the navigation bar. - {{< nav-icon "settings" >}} + {{< nav-icon "settings" "v2" >}} 2. Select the **Variables** tab. -3. Hover over a variable, click the **{{< icon "trash" >}}** icon, and **Delete**. +3. Hover over a variable, click the **{{< icon "trash" "v2" >}}** icon, and **Delete**. {{% warn %}} Once deleted, any dashboards with queries that utilize the variable will no diff --git a/content/influxdb/v2.0/visualize-data/variables/export-variable.md b/content/influxdb/v2.0/visualize-data/variables/export-variable.md index 745da0637d..873d9acac2 100644 --- a/content/influxdb/v2.0/visualize-data/variables/export-variable.md +++ b/content/influxdb/v2.0/visualize-data/variables/export-variable.md @@ -15,10 +15,10 @@ Variables are exported as downloadable JSON files. 1. Click the **Settings** icon in the navigation bar. - {{< nav-icon "settings" >}} + {{< nav-icon "settings" "v2" >}} 2. Select the **Variables** tab. -3. Hover over a variable in the list, then click the gear icon (**{{< icon "gear" >}}**) +3. Hover over a variable in the list, then click the gear icon (**{{< icon "gear" "v2" >}}**) and select **Export**. 4. Review the JSON in the window that appears. 5. Select one of the following options: diff --git a/content/influxdb/v2.0/visualize-data/variables/update-variable.md b/content/influxdb/v2.0/visualize-data/variables/update-variable.md index a3407e8a3d..56fb0570c3 100644 --- a/content/influxdb/v2.0/visualize-data/variables/update-variable.md +++ b/content/influxdb/v2.0/visualize-data/variables/update-variable.md @@ -15,7 +15,7 @@ Update an existing dashboard variable's name or JSON content in the InfluxDB use 1. Click the **Settings** icon in the navigation bar. - {{< nav-icon "settings" >}} + {{< nav-icon "settings" "v2" >}} 2. Select the **Variables** tab. 3. Click a variable's name from the list. diff --git a/content/influxdb/v2.0/visualize-data/variables/view-variables.md b/content/influxdb/v2.0/visualize-data/variables/view-variables.md index 981e3dd43e..98ea87a86c 100644 --- a/content/influxdb/v2.0/visualize-data/variables/view-variables.md +++ b/content/influxdb/v2.0/visualize-data/variables/view-variables.md @@ -15,7 +15,7 @@ View a list of dashboard variables in the InfluxDB user interface (UI) from an o 1. Click the **Settings** icon in the navigation bar. - {{< nav-icon "settings" >}} + {{< nav-icon "settings" "v2" >}} 3. Select the **Variables** tab. @@ -23,7 +23,7 @@ View a list of dashboard variables in the InfluxDB user interface (UI) from an o 1. Click the **Data Explorer** icon in the navigation bar. - {{< nav-icon "data-explorer" >}} + {{< nav-icon "data-explorer" "v2" >}} 2. Switch to **Script Editor**. 3. Click the **Variables** tab to the right of the script editor. diff --git a/content/influxdb/v2.0/visualize-data/visualization-types/band.md b/content/influxdb/v2.0/visualize-data/visualization-types/band.md index 8974ef8f16..2ee129368f 100644 --- a/content/influxdb/v2.0/visualize-data/visualization-types/band.md +++ b/content/influxdb/v2.0/visualize-data/visualization-types/band.md @@ -20,7 +20,7 @@ To see bands (boundaries) in the **Band Plot** visualization, you must set up tw 1. Click the **Data Explorer** icon in the navigation bar. - {{< nav-icon "data-explorer" >}} + {{< nav-icon "data-explorer" "v2" >}} 2. Enter your query (see [Explore data with Flux and the Data Explorer](/influxdb/v2.0/visualize-data/explore-metrics/#explore-data-with-flux-and-the-data-explorer)). You must include the aggregate functions used to determine the Band Plot visualization boundaries in your query. 3. Select the **Band Plot** option from the visualization dropdown in the upper left, and then click **Customize**. @@ -41,7 +41,7 @@ To see bands (boundaries) in the **Band Plot** visualization, you must set up tw 1. Click the **Data Explorer** icon in the navigation bar. - {{< nav-icon "data-explorer" >}} + {{< nav-icon "data-explorer" "v2" >}} 2. Click **Script Editor**. 3. Select the **Band Plot** option from the visualization dropdown in the upper left. @@ -95,7 +95,7 @@ For example, in the band chart above, the lines represent the mean `usage_system ## Band controls -To view **Band** controls, click **{{< icon "gear" >}} Customize** next to the visualization dropdown. +To view **Band** controls, click **{{< icon "gear" "v2" >}} Customize** next to the visualization dropdown. ###### Data diff --git a/content/influxdb/v2.0/visualize-data/visualization-types/gauge.md b/content/influxdb/v2.0/visualize-data/visualization-types/gauge.md index 2322e43499..e6cfe0467a 100644 --- a/content/influxdb/v2.0/visualize-data/visualization-types/gauge.md +++ b/content/influxdb/v2.0/visualize-data/visualization-types/gauge.md @@ -30,7 +30,7 @@ For consistent results, the Gauge query should return a single table. {{% /note %}} ## Gauge Controls -To view **Gauge** controls, click **{{< icon "gear" >}} Customize** next to +To view **Gauge** controls, click **{{< icon "gear" "v2" >}} Customize** next to the visualization dropdown. - **Prefix**: Prefix to add to the gauge. diff --git a/content/influxdb/v2.0/visualize-data/visualization-types/graph-single-stat.md b/content/influxdb/v2.0/visualize-data/visualization-types/graph-single-stat.md index bf0e219425..ad95a40a1f 100644 --- a/content/influxdb/v2.0/visualize-data/visualization-types/graph-single-stat.md +++ b/content/influxdb/v2.0/visualize-data/visualization-types/graph-single-stat.md @@ -38,7 +38,7 @@ For consistent Single Stat results, the query should return a single table. {{% /note %}} ## Graph + Single Stat Controls -To view **Graph + Single Stat** controls, click **{{< icon "gear" >}} Customize** next to +To view **Graph + Single Stat** controls, click **{{< icon "gear" "v2" >}} Customize** next to the visualization dropdown. ###### Data diff --git a/content/influxdb/v2.0/visualize-data/visualization-types/graph.md b/content/influxdb/v2.0/visualize-data/visualization-types/graph.md index 3312816dae..49299f9755 100644 --- a/content/influxdb/v2.0/visualize-data/visualization-types/graph.md +++ b/content/influxdb/v2.0/visualize-data/visualization-types/graph.md @@ -25,7 +25,7 @@ When multiple series are present, it automatically assigns colors based on the s When using a line graph, all points within a single table are connected. When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options). ## Graph controls -To view **Graph** controls, click **{{< icon "gear" >}} Customize** next to +To view **Graph** controls, click **{{< icon "gear" "v2" >}} Customize** next to the visualization dropdown. ###### Data diff --git a/content/influxdb/v2.0/visualize-data/visualization-types/heatmap.md b/content/influxdb/v2.0/visualize-data/visualization-types/heatmap.md index 44f07c0d2c..094f0b1a97 100644 --- a/content/influxdb/v2.0/visualize-data/visualization-types/heatmap.md +++ b/content/influxdb/v2.0/visualize-data/visualization-types/heatmap.md @@ -29,7 +29,7 @@ The total number of points that fall within a bin determine the its value and co Warmer or brighter colors represent higher bin values or density of points within the bin. ## Heatmap Controls -To view **Heatmap** controls, click **{{< icon "gear" >}} Customize** next to +To view **Heatmap** controls, click **{{< icon "gear" "v2" >}} Customize** next to the visualization dropdown. ###### Data diff --git a/content/influxdb/v2.0/visualize-data/visualization-types/histogram.md b/content/influxdb/v2.0/visualize-data/visualization-types/histogram.md index 49b0919f69..3ff1fea8fd 100644 --- a/content/influxdb/v2.0/visualize-data/visualization-types/histogram.md +++ b/content/influxdb/v2.0/visualize-data/visualization-types/histogram.md @@ -33,7 +33,7 @@ To work properly, query results **should not** be structured as histogram data. {{% /note %}} ## Histogram Controls -To view **Histogram** controls, click **{{< icon "gear" >}} Customize** next to +To view **Histogram** controls, click **{{< icon "gear" "v2" >}} Customize** next to the visualization dropdown. ###### Data diff --git a/content/influxdb/v2.0/visualize-data/visualization-types/mosaic.md b/content/influxdb/v2.0/visualize-data/visualization-types/mosaic.md index 463afc27cb..0deea22ad0 100644 --- a/content/influxdb/v2.0/visualize-data/visualization-types/mosaic.md +++ b/content/influxdb/v2.0/visualize-data/visualization-types/mosaic.md @@ -24,7 +24,7 @@ The mosaic visualization displays colored tiles based on string values in a spec Each unique string value is represented by a different color. ## Mosaic controls -To view **Mosaic** controls, click **{{< icon "gear" >}} Customize** next to the visualization dropdown. +To view **Mosaic** controls, click **{{< icon "gear" "v2" >}} Customize** next to the visualization dropdown. ###### Data - **Fill Column**: Select a column to fill in the mosaic tiles. diff --git a/content/influxdb/v2.0/visualize-data/visualization-types/scatter.md b/content/influxdb/v2.0/visualize-data/visualization-types/scatter.md index cb742e2dbe..51f8eae278 100644 --- a/content/influxdb/v2.0/visualize-data/visualization-types/scatter.md +++ b/content/influxdb/v2.0/visualize-data/visualization-types/scatter.md @@ -27,7 +27,7 @@ Use the [Symbol Column](#data) and [Fill Column](#data) options to select column used to differentiate points in the visualization. ## Scatter controls -To view **Scatter** controls, click **{{< icon "gear" >}} Customize** next to +To view **Scatter** controls, click **{{< icon "gear" "v2" >}} Customize** next to the visualization dropdown. ###### Data diff --git a/content/influxdb/v2.0/visualize-data/visualization-types/single-stat.md b/content/influxdb/v2.0/visualize-data/visualization-types/single-stat.md index 654a4a2a1b..d8d2bd5b19 100644 --- a/content/influxdb/v2.0/visualize-data/visualization-types/single-stat.md +++ b/content/influxdb/v2.0/visualize-data/visualization-types/single-stat.md @@ -30,7 +30,7 @@ For consistent results, the Single Stat query should return a single table. {{% /note %}} ## Single Stat Controls -To view **Single Stat** controls, click **{{< icon "gear" >}} Customize** next to +To view **Single Stat** controls, click **{{< icon "gear" "v2" >}} Customize** next to the visualization dropdown. - **Prefix**: Prefix to be added to the single stat. diff --git a/content/influxdb/v2.0/visualize-data/visualization-types/table.md b/content/influxdb/v2.0/visualize-data/visualization-types/table.md index d46273ac20..1809ab61cd 100644 --- a/content/influxdb/v2.0/visualize-data/visualization-types/table.md +++ b/content/influxdb/v2.0/visualize-data/visualization-types/table.md @@ -27,7 +27,7 @@ Select other output tables in the far left column of the table visualization. Tables are identified by their [group key](/{{< latest "flux" >}}/get-started/data-model/#group-key). ## Table Controls -To view **Table** controls, click **{{< icon "gear" >}} Customize** next to +To view **Table** controls, click **{{< icon "gear" "v2" >}} Customize** next to the visualization dropdown. ###### Formatting diff --git a/content/influxdb/v2.0/write-data/delete-data.md b/content/influxdb/v2.0/write-data/delete-data.md index e817106119..861b912066 100644 --- a/content/influxdb/v2.0/write-data/delete-data.md +++ b/content/influxdb/v2.0/write-data/delete-data.md @@ -38,7 +38,7 @@ Delete data from buckets you've created. You cannot delete data from system buck 1. Click the **Data Explorer** icon in the sidebar. - {{< nav-icon "data-explorer" >}} + {{< nav-icon "data-explorer" "v2" >}} 2. Click **Delete Data** in the top navigation bar. 3. In the **Delete Data** window that appears: diff --git a/content/influxdb/v2.0/write-data/no-code/load-data.md b/content/influxdb/v2.0/write-data/no-code/load-data.md index ca8be9ab78..0414d4d9d0 100644 --- a/content/influxdb/v2.0/write-data/no-code/load-data.md +++ b/content/influxdb/v2.0/write-data/no-code/load-data.md @@ -25,7 +25,7 @@ Load data from the following sources in the InfluxDB user interface (UI): Load CSV or line protocol data by uploading a file or pasting the data manually into the UI. 1. In the navigation menu on the left, click **Data (Load Data)** > **Sources**. - {{< nav-icon "data" >}} + {{< nav-icon "data" "v2" >}} 2. Under **File Upload**, select the type of data to upload: - **Annotated CSV**. Verify your CSV file follows the supported [annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/) syntax. - **Line Protocol**. Verify your line protocol file adheres to the following conventions: @@ -47,7 +47,7 @@ Load CSV or line protocol data by uploading a file or pasting the data manually ### Load data from a client library in the UI 1. In the navigation menu on the left, click **Data (Load Data)** > **Sources**. - {{< nav-icon "data" >}} + {{< nav-icon "data" "v2" >}} 2. Do one of the following: - Enter a specific client library to search for in the **Search data writing methods** field. - Scroll down to browse available client libraries. @@ -62,7 +62,7 @@ Load CSV or line protocol data by uploading a file or pasting the data manually ### Load data from a Telegraf plugin in the UI 1. In the navigation menu on the left, click **Data (Load Data)** > **Sources**. - {{< nav-icon "data" >}} + {{< nav-icon "data" "v2" >}} 2. Do one of the following: - Enter a specific Telegraf plugin to search for in the **Search data writing methods** field. - Scroll down to **Telegraf Plugins** and browse available input plugins. diff --git a/content/influxdb/v2.0/write-data/no-code/scrape-data/manage-scrapers/create-a-scraper.md b/content/influxdb/v2.0/write-data/no-code/scrape-data/manage-scrapers/create-a-scraper.md index 15552e9f8a..84d0ab5a70 100644 --- a/content/influxdb/v2.0/write-data/no-code/scrape-data/manage-scrapers/create-a-scraper.md +++ b/content/influxdb/v2.0/write-data/no-code/scrape-data/manage-scrapers/create-a-scraper.md @@ -19,7 +19,7 @@ Create a new scraper in the InfluxDB user interface (UI). {{< nav-icon "load data" >}} -3. Click **{{< icon "plus" >}} Create Scraper**. +3. Click **{{< icon "plus" "v2" >}} Create Scraper**. 4. Enter a **Name** for the scraper. 5. Select a **Bucket** to store the scraped data. 6. Enter the **Target URL** to scrape. diff --git a/content/influxdb/v2.0/write-data/no-code/scrape-data/manage-scrapers/delete-a-scraper.md b/content/influxdb/v2.0/write-data/no-code/scrape-data/manage-scrapers/delete-a-scraper.md index c0ed3c5104..bb27440b45 100644 --- a/content/influxdb/v2.0/write-data/no-code/scrape-data/manage-scrapers/delete-a-scraper.md +++ b/content/influxdb/v2.0/write-data/no-code/scrape-data/manage-scrapers/delete-a-scraper.md @@ -19,5 +19,5 @@ Delete a scraper from the InfluxDB user interface (UI). {{< nav-icon "load data" >}} -3. Hover over the scraper you want to delete and click the **{{< icon "delete" >}}** icon. +3. Hover over the scraper you want to delete and click the **{{< icon "delete" "v2" >}}** icon. 4. Click **Delete**. diff --git a/content/influxdb/v2.0/write-data/no-code/scrape-data/manage-scrapers/update-a-scraper.md b/content/influxdb/v2.0/write-data/no-code/scrape-data/manage-scrapers/update-a-scraper.md index 232b29a73d..e3fcd12300 100644 --- a/content/influxdb/v2.0/write-data/no-code/scrape-data/manage-scrapers/update-a-scraper.md +++ b/content/influxdb/v2.0/write-data/no-code/scrape-data/manage-scrapers/update-a-scraper.md @@ -24,5 +24,5 @@ To modify either, [create a new scraper](/influxdb/v2.0/write-data/no-code/scrap {{< nav-icon "load data" >}} -3. Hover over the scraper you would like to update and click the **{{< icon "pencil" >}}** that appears next to the scraper name. +3. Hover over the scraper you would like to update and click the **{{< icon "pencil" "v2" >}}** that appears next to the scraper name. 4. Enter a new name for the scraper. Press Return or click out of the name field to save the change. diff --git a/content/influxdb/v2.0/write-data/no-code/use-telegraf/auto-config.md b/content/influxdb/v2.0/write-data/no-code/use-telegraf/auto-config.md index 33f7764738..2c6b71a6a8 100644 --- a/content/influxdb/v2.0/write-data/no-code/use-telegraf/auto-config.md +++ b/content/influxdb/v2.0/write-data/no-code/use-telegraf/auto-config.md @@ -33,11 +33,11 @@ for using Telegraf with InfluxDB v2.0._ {{< nav-icon "load data" >}} -4. Click **{{< icon "plus" >}} Create Configuration**. +4. Click **{{< icon "plus" "v2" >}} Create Configuration**. 5. In the **Bucket** dropdown, select the bucket where Telegraf will store collected data. 6. Select one or more of the available plugin groups and click **Continue**. 7. Review the list of **Plugins to Configure** for configuration requirements. - Plugins listed with a {{< icon "check" >}} + Plugins listed with a {{< icon "check" "v2" >}} require no additional configuration. To configure a plugin or access plugin documentation, click the plugin name. 5. Provide a **Telegraf Configuration Name** and an optional **Telegraf Configuration Description**. diff --git a/content/influxdb/v2.1/_index.md b/content/influxdb/v2.1/_index.md new file mode 100644 index 0000000000..719cf97ca0 --- /dev/null +++ b/content/influxdb/v2.1/_index.md @@ -0,0 +1,19 @@ +--- +title: InfluxDB OSS 2.1 documentation +description: > + InfluxDB OSS is an open source time series database designed to handle high write and query loads. + Learn how to use and leverage InfluxDB in use cases such as monitoring metrics, IoT data, and events. +layout: landing-influxdb +menu: + influxdb_2_1: + name: InfluxDB OSS 2.1 +weight: 1 +--- + +#### Welcome +Welcome to the InfluxDB v2.1 documentation! +InfluxDB is an open source time series database designed to handle high write and query workloads. + +This documentation is meant to help you learn how to use and leverage InfluxDB to meet your needs. +Common use cases include infrastructure monitoring, IoT data collection, events handling, and more. +If your use case involves time series data, InfluxDB is purpose-built to handle it. diff --git a/content/influxdb/v2.1/api-guide/_index.md b/content/influxdb/v2.1/api-guide/_index.md new file mode 100644 index 0000000000..ea05be34e1 --- /dev/null +++ b/content/influxdb/v2.1/api-guide/_index.md @@ -0,0 +1,33 @@ +--- +title: Develop with the InfluxDB API +seotitle: Use the InfluxDB API +description: Interact with InfluxDB 2.1 using a rich API for writing and querying data and more. +weight: 4 +menu: + influxdb_2_1: + name: Develop with the API +influxdb/v2.1/tags: [api] +--- + +The InfluxDB v2 API provides a programmatic interface for interactions with InfluxDB. +Access the InfluxDB API using the `/api/v2/` endpoint. + +## InfluxDB client libraries +InfluxDB client libraries are language-specific packages that integrate with the InfluxDB v2 API. +For information about supported client libraries, see [InfluxDB client libraries](/{{< latest "influxdb" >}}/api-guide/client-libraries/). + +## InfluxDB v2 API documentation +InfluxDB OSS {{< current-version >}} API documentation + +#### View InfluxDB API documentation locally +InfluxDB API documentation is built into the `influxd` service and represents +the API specific to the current version of InfluxDB. +To view the API documentation locally, [start InfluxDB](/influxdb/v2.1/get-started/#start-influxdb) +and visit the `/docs` endpoint in a browser ([localhost:8086/docs](http://localhost:8086/docs)). + +## InfluxDB v1 compatibility API documentation +The InfluxDB v2 API includes [InfluxDB 1.x compatibility endpoints](/influxdb/v2.1/reference/api/influxdb-1x/) +that work with InfluxDB 1.x client libraries and third-party integrations like +[Grafana](https://grafana.com) and others. + +View full v1 compatibility API documentation diff --git a/content/influxdb/v2.1/api-guide/api_intro.md b/content/influxdb/v2.1/api-guide/api_intro.md new file mode 100644 index 0000000000..d75bc3eb30 --- /dev/null +++ b/content/influxdb/v2.1/api-guide/api_intro.md @@ -0,0 +1,75 @@ +--- +title: API Quick Start +seotitle: Use the InfluxDB API +description: Interact with InfluxDB 1 using a rich API for writing and querying data and more. +weight: 3 +menu: + influxdb_2_1: + name: Quick Start + parent: Develop with the API +aliases: + - /influxdb/v2.1/tools/api/ +influxdb/cloud/tags: [api] +--- + +InfluxDB offers a rich API and [client libraries](/influxdb/v2.1/api-guide/client-libraries) ready to integrate with your application. Use popular tools like Curl and [Postman](/influxdb/v2.1/api-guide/postman) for rapidly testing API requests. + +This section will guide you through the most commonly used API methods. + +For detailed documentation on the entire API, see [InfluxDBv2 API Reference](/influxdb/v2.1/reference/api/#influxdb-v2-api-documentation). + +{{% note %}} +If you need to use InfluxDB {{< current-version >}} with **InfluxDB 1.x** API clients and integrations, see the [1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). +{{% /note %}} + +## Bootstrap your application + +With most API requests, you'll need to provide a minimum of your InfluxDB URL, Organization, and Authorization Token. + +[Install InfluxDB OSS v2.x](/influxdb/v2.1/install/) or upgrade to +an [InfluxDB Cloud account](/influxdb/cloud/sign-up). + +### Authentication + +InfluxDB uses [API tokens](/influxdb/v2.1/security/tokens/) to authorize API requests. + +1. Before exploring the API, use the InfluxDB UI to +[create an initial API token](/influxdb/v2.1/security/tokens/create-token/) for your application. + +2. Include your API token in an `Authentication: Token YOUR_API_TOKEN` HTTP header with each request. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[curl](#curl) +[Node.js](#nodejs) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +{{% get-shared-text "api/v2.0/auth/oss/token-auth.sh" %}} +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```js +{{% get-shared-text "api/v2.0/auth/oss/token-auth.js" %}} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +Postman is another popular tool for exploring APIs. See how to [send authenticated requests with Postman](/{{< latest "influxdb" >}}/api-guide/postman/#send-authenticated-api-requests-with-postman). + +## Buckets API + +Before writing data you'll need to create a Bucket in InfluxDB. +[Create a bucket](/influxdb/v2.1/organizations/buckets/create-bucket/#create-a-bucket-using-the-influxdb-api) using an HTTP request to the InfluxDB API `/buckets` endpoint. + +```sh +{{% get-shared-text "api/v2.0/buckets/oss/create.sh" %}} +``` + +## Write API + +[Write data to InfluxDB](/influxdb/v2.1/write-data/developer-tools/api/) using an HTTP request to the InfluxDB API `/write` endpoint. + +## Query API + +[Query from InfluxDB](/influxdb/v2.1/query-data/execute-queries/influx-api/) using an HTTP request to the `/query` endpoint. diff --git a/content/influxdb/v2.1/api-guide/client-libraries/_index.md b/content/influxdb/v2.1/api-guide/client-libraries/_index.md new file mode 100644 index 0000000000..93b0458100 --- /dev/null +++ b/content/influxdb/v2.1/api-guide/client-libraries/_index.md @@ -0,0 +1,26 @@ +--- +title: Use InfluxDB client libraries +description: > + InfluxDB client libraries are language-specific tools that integrate with the InfluxDB v2 API. + View the list of available client libraries. +weight: 101 +aliases: + - /influxdb/v2.1/reference/client-libraries/ + - /influxdb/v2.1/reference/api/client-libraries/ + - /influxdb/v2.1/tools/client-libraries/ +menu: + influxdb_2_1: + name: Client libraries + parent: Develop with the API +influxdb/v2.1/tags: [client libraries] +--- + +InfluxDB client libraries are language-specific packages that integrate with the InfluxDB v2 API. +The following **InfluxDB v2** client libraries are available: + +{{% note %}} +These client libraries are in active development and may not be feature-complete. +This list will continue to grow as more client libraries are released. +{{% /note %}} + +{{< children type="list" >}} diff --git a/content/influxdb/v2.1/api-guide/client-libraries/arduino.md b/content/influxdb/v2.1/api-guide/client-libraries/arduino.md new file mode 100644 index 0000000000..222e7c38b0 --- /dev/null +++ b/content/influxdb/v2.1/api-guide/client-libraries/arduino.md @@ -0,0 +1,14 @@ +--- +title: Arduino client library +seotitle: Use the InfluxDB Arduino client library +list_title: Arduino +description: Use the InfluxDB Arduino client library to interact with InfluxDB. +external_url: https://github.com/tobiasschuerg/InfluxDB-Client-for-Arduino +list_note: _– contributed by [tobiasschuerg](https://github.com/tobiasschuerg)_ +menu: + influxdb_2_1: + name: Arduino + parent: Client libraries + url: https://github.com/tobiasschuerg/InfluxDB-Client-for-Arduino +weight: 201 +--- diff --git a/content/influxdb/v2.1/api-guide/client-libraries/browserjs.md b/content/influxdb/v2.1/api-guide/client-libraries/browserjs.md new file mode 100644 index 0000000000..f9b75ef48f --- /dev/null +++ b/content/influxdb/v2.1/api-guide/client-libraries/browserjs.md @@ -0,0 +1,118 @@ +--- +title: JavaScript client library for web browsers +seotitle: Use the InfluxDB JavaScript client library for web browsers +list_title: JavaScript for browsers +description: > + Use the InfluxDB JavaScript client library to interact with InfluxDB in web clients. +menu: + influxdb_2_1: + name: JavaScript for browsers + identifier: client_js_browsers + parent: Client libraries +influxdb/v2.1/tags: [client libraries, JavaScript] +weight: 201 +aliases: + - /influxdb/v2.1/reference/api/client-libraries/browserjs/ + - /influxdb/v2.1/api-guide/client-libraries/browserjs/write + - /influxdb/v2.1/api-guide/client-libraries/browserjs/query +related: + - /influxdb/v2.1/api-guide/client-libraries/nodejs/write/ + - /influxdb/v2.1/api-guide/client-libraries/nodejs/query/ +--- + +Use the [InfluxDB JavaScript client library](https://github.com/influxdata/influxdb-client-js) to interact with the InfluxDB API in browsers and front-end clients. This library supports both front-end and server-side environments and provides the following distributions: +* ECMAScript modules (ESM) and CommonJS modules (CJS) +* Bundled ESM +* Bundled UMD + +This guide presumes some familiarity with JavaScript, browser environments, and InfluxDB. +If you're just getting started with InfluxDB, see [Get started with InfluxDB](/{{% latest "influxdb" %}}/get-started/). + +{{% warn %}} +### Tokens in production applications +{{% api/browser-token-warning %}} +{{% /warn %}} + +* [Before you begin](#before-you-begin) +* [Use with module bundlers](#use-with-module-bundlers) +* [Use bundled distributions with browsers and module loaders](#use-bundled-distributions-with-browsers-and-module-loaders) +* [Get started with the example app](#get-started-with-the-example-app) + +## Before you begin + +1. Install [Node.js](https://nodejs.org/en/download/package-manager/) to serve your front-end app. + +2. Ensure that InfluxDB is running and you can connect to it. + For information about what URL to use to connect to InfluxDB OSS or InfluxDB Cloud, see [InfluxDB URLs](/{{% latest "influxdb" %}}/reference/urls/). + +## Use with module bundlers + +If you use a module bundler like Webpack or Parcel, install `@influxdata/influxdb-client-browser`. +For more information and examples, see [Node.js](/{{% latest "influxdb" %}}/api-guide/client-libraries/nodejs/). + +## Use bundled distributions with browsers and module loaders + +1. Configure InfluxDB properties for your script. + + ```html + + ``` + +2. Import modules from the latest client library browser distribution. +`@influxdata/influxdb-client-browser` exports bundled ESM and UMD syntaxes. + + {{< code-tabs-wrapper >}} + {{% code-tabs %}} + [ESM](#import-esm) + [UMD](#import-umd) + {{% /code-tabs %}} + {{% code-tab-content %}} + ```html + + ``` + {{% /code-tab-content %}} + {{% code-tab-content %}} + ```html + + + ``` + {{% /code-tab-content %}} + {{< /code-tabs-wrapper >}} + +After you've imported the client library, you're ready to [write data](/{{% latest "influxdb" %}}/api-guide/client-libraries/nodejs/write/?t=nodejs) to InfluxDB. + +## Get started with the example app + +This library includes an example browser app that queries from and writes to your InfluxDB instance. + +1. Clone the [influxdb-client-js](https://github.com/influxdata/influxdb-client-js) repo. + +2. Navigate to the `examples` directory: + ```js + cd examples + ``` + +3. Update `./env_browser.js` with your InfluxDB [url](/{{% latest "influxdb" %}}/reference/urls/), [bucket](/{{% latest "influxdb" %}}/organizations/buckets/), [organization](/{{% latest "influxdb" %}}/organizations/), and [token](/{{% latest "influxdb" %}}/security/tokens/) + +4. Run the following command to start the application at [http://localhost:3001/examples/index.html]() + + ```sh + npm run browser + ``` + + `index.html` loads the `env_browser.js` configuration, the client library ESM modules, and the application in your browser. + diff --git a/content/influxdb/v2.1/api-guide/client-libraries/csharp.md b/content/influxdb/v2.1/api-guide/client-libraries/csharp.md new file mode 100644 index 0000000000..cc1926510d --- /dev/null +++ b/content/influxdb/v2.1/api-guide/client-libraries/csharp.md @@ -0,0 +1,13 @@ +--- +title: C# client library +list_title: C# +seotitle: Use the InfluxDB C# client library +description: Use the InfluxDB C# client library to interact with InfluxDB. +external_url: https://github.com/influxdata/influxdb-client-csharp +menu: + influxdb_2_1: + name: C# + parent: Client libraries + url: https://github.com/influxdata/influxdb-client-csharp +weight: 201 +--- diff --git a/content/influxdb/v2.1/api-guide/client-libraries/go.md b/content/influxdb/v2.1/api-guide/client-libraries/go.md new file mode 100644 index 0000000000..b9fba446f5 --- /dev/null +++ b/content/influxdb/v2.1/api-guide/client-libraries/go.md @@ -0,0 +1,206 @@ +--- +title: Go client library +seotitle: Use the InfluxDB Go client library +list_title: Go +description: > + Use the InfluxDB Go client library to interact with InfluxDB. +menu: + influxdb_2_1: + name: Go + parent: Client libraries +influxdb/v2.1/tags: [client libraries, Go] +weight: 201 +aliases: + - /influxdb/v2.1/reference/api/client-libraries/go/ + - /influxdb/v2.1/tools/client-libraries/go/ +--- + +Use the [InfluxDB Go client library](https://github.com/influxdata/influxdb-client-go) to integrate InfluxDB into Go scripts and applications. + +This guide presumes some familiarity with Go and InfluxDB. +If just getting started, see [Get started with InfluxDB](/influxdb/v2.1/get-started/). + +## Before you begin + +1. [Install Go 1.13 or later](https://golang.org/doc/install). +2. Add the client package your to your project dependencies. + + ```sh + # Add InfluxDB Go client package to your project go.mod + go get github.com/influxdata/influxdb-client-go + ``` +3. Ensure that InfluxDB is running and you can connect to it. + For information about what URL to use to connect to InfluxDB OSS or InfluxDB Cloud, see [InfluxDB URLs](/influxdb/v2.1/reference/urls/). + +## Boilerplate for the InfluxDB Go Client Library + +Use the Go library to write and query data from InfluxDB. + +1. In your Go program, import the necessary packages and specify the entry point of your executable program. + + ```go + package main + + import ( + "context" + "fmt" + "time" + + "github.com/influxdata/influxdb-client-go/v2" + ) + ``` + +2. Define variables for your InfluxDB [bucket](/influxdb/v2.1/organizations/buckets/), [organization](/influxdb/v2.1/organizations/), and [token](/influxdb/v2.1/security/tokens/). + + ```go + bucket := "example-bucket" + org := "example-org" + token := "example-token" + // Store the URL of your InfluxDB instance + url := "http://localhost:8086" + ``` + +3. Create the the InfluxDB Go client and pass in the `url` and `token` parameters. + + ```go + client := influxdb2.NewClient(url, token) + ``` + +4. Create a **write client** with the `WriteAPIBlocking` method and pass in the `org` and `bucket` parameters. + + ```go + writeAPI := client.WriteAPIBlocking(org, bucket) + ``` + +5. To query data, create an InfluxDB **query client** and pass in your InfluxDB `org`. + + ```go + queryAPI := client.QueryAPI(org) + ``` + +## Write data to InfluxDB with Go + +Use the Go library to write data to InfluxDB. + +1. Create a [point](/influxdb/v2.1/reference/glossary/#point) and write it to InfluxDB using the `WritePoint` method of the API writer struct. + +2. Close the client to flush all pending writes and finish. + + ```go + p := influxdb2.NewPoint("stat", + map[string]string{"unit": "temperature"}, + map[string]interface{}{"avg": 24.5, "max": 45}, + time.Now()) + writeAPI.WritePoint(context.Background(), p) + client.Close() + ``` + +### Complete example write script + +```go +func main() { + bucket := "example-bucket" + org := "example-org" + token := "example-token" + // Store the URL of your InfluxDB instance + url := "http://localhost:8086" + // Create new client with default option for server url authenticate by token + client := influxdb2.NewClient(url, token) + // User blocking write client for writes to desired bucket + writeAPI := client.WriteAPIBlocking(org, bucket) + // Create point using full params constructor + p := influxdb2.NewPoint("stat", + map[string]string{"unit": "temperature"}, + map[string]interface{}{"avg": 24.5, "max": 45}, + time.Now()) + // Write point immediately + writeAPI.WritePoint(context.Background(), p) + // Ensures background processes finishes + client.Close() +} +``` +## Query data from InfluxDB with Go +Use the Go library to query data to InfluxDB. + +1. Create a Flux query and supply your `bucket` parameter. + + ```js + from(bucket:"") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "stat") + ``` + + The query client sends the Flux query to InfluxDB and returns the results as a FluxRecord object with a table structure. + +**The query client includes the following methods:** + +- `Query`: Sends the Flux query to InfluxDB. +- `Next`: Iterates over the query response. +- `TableChanged`: Identifies when the group key changes. +- `Record`: Returns the last parsed FluxRecord and gives access to value and row properties. +- `Value`: Returns the actual field value. + +```go +result, err := queryAPI.Query(context.Background(), `from(bucket:"") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "stat")`) +if err == nil { + for result.Next() { + if result.TableChanged() { + fmt.Printf("table: %s\n", result.TableMetadata().String()) + } + fmt.Printf("value: %v\n", result.Record().Value()) + } + if result.Err() != nil { + fmt.Printf("query parsing error: %s\n", result.Err().Error()) + } +} else { + panic(err) +} +``` + +**The FluxRecord object includes the following methods for accessing your data:** + +- `Table()`: Returns the index of the table the record belongs to. +- `Start()`: Returns the inclusive lower time bound of all records in the current table. +- `Stop()`: Returns the exclusive upper time bound of all records in the current table. +- `Time()`: Returns the time of the record. +- `Value() `: Returns the actual field value. +- `Field()`: Returns the field name. +- `Measurement()`: Returns the measurement name of the record. +- `Values()`: Returns a map of column values. +- `ValueByKey()`: Returns a value from the record for given column key. + +### Complete example query script + +```go + func main() { + // Create client + client := influxdb2.NewClient(url, token) + // Get query client + queryAPI := client.QueryAPI(org) + // Get QueryTableResult + result, err := queryAPI.Query(context.Background(), `from(bucket:"my-bucket")|> range(start: -1h) |> filter(fn: (r) => r._measurement == "stat")`) + if err == nil { + // Iterate over query response + for result.Next() { + // Notice when group key has changed + if result.TableChanged() { + fmt.Printf("table: %s\n", result.TableMetadata().String()) + } + // Access data + fmt.Printf("value: %v\n", result.Record().Value()) + } + // Check for an error + if result.Err() != nil { + fmt.Printf("query parsing error: %s\n", result.Err().Error()) + } + } else { + panic(err) + } + // Ensures background processes finishes + client.Close() +} +``` + +For more information, see the [Go client README on GitHub](https://github.com/influxdata/influxdb-client-go). diff --git a/content/influxdb/v2.1/api-guide/client-libraries/java.md b/content/influxdb/v2.1/api-guide/client-libraries/java.md new file mode 100644 index 0000000000..05181f1ddb --- /dev/null +++ b/content/influxdb/v2.1/api-guide/client-libraries/java.md @@ -0,0 +1,13 @@ +--- +title: Java client library +seotitle: Use the InfluxDB Java client library +list_title: Java +description: Use the Java client library to interact with InfluxDB. +external_url: https://github.com/influxdata/influxdb-client-java +menu: + influxdb_2_1: + name: Java + parent: Client libraries + url: https://github.com/influxdata/influxdb-client-java +weight: 201 +--- diff --git a/content/influxdb/v2.1/api-guide/client-libraries/kotlin.md b/content/influxdb/v2.1/api-guide/client-libraries/kotlin.md new file mode 100644 index 0000000000..abb94d2505 --- /dev/null +++ b/content/influxdb/v2.1/api-guide/client-libraries/kotlin.md @@ -0,0 +1,13 @@ +--- +title: Kotlin client library +seotitle: Use the Kotlin client library +list_title: Kotlin +description: Use the InfluxDB Kotlin client library to interact with InfluxDB. +external_url: https://github.com/influxdata/influxdb-client-java/tree/master/client-kotlin +menu: + influxdb_2_1: + name: Kotlin + parent: Client libraries + url: https://github.com/influxdata/influxdb-client-java/tree/master/client-kotlin +weight: 201 +--- diff --git a/content/influxdb/v2.1/api-guide/client-libraries/nodejs/_index.md b/content/influxdb/v2.1/api-guide/client-libraries/nodejs/_index.md new file mode 100644 index 0000000000..2ab9f62963 --- /dev/null +++ b/content/influxdb/v2.1/api-guide/client-libraries/nodejs/_index.md @@ -0,0 +1,23 @@ +--- +title: Node.js JavaScript client library +seotitle: Use the InfluxDB JavaScript client library +list_title: Node.js +description: > + Use the InfluxDB Node.js JavaScript client library to interact with InfluxDB. +menu: + influxdb_2_1: + name: Node.js + parent: Client libraries +influxdb/v2.1/tags: [client libraries, JavaScript] +weight: 201 +aliases: + - /influxdb/v2.1/reference/api/client-libraries/nodejs/ + - /influxdb/v2.1/reference/api/client-libraries/js/ +--- + +Use the [InfluxDB JavaScript client library](https://github.com/influxdata/influxdb-client-js) to integrate InfluxDB into your Node.js application. +In this guide, you'll start a Node.js project from scratch and code some simple API operations. + +{{< children >}} + +{{% api/v2dot0/nodejs/learn-more %}} diff --git a/content/influxdb/v2.1/api-guide/client-libraries/nodejs/install.md b/content/influxdb/v2.1/api-guide/client-libraries/nodejs/install.md new file mode 100644 index 0000000000..5396d40f14 --- /dev/null +++ b/content/influxdb/v2.1/api-guide/client-libraries/nodejs/install.md @@ -0,0 +1,97 @@ +--- +title: Install the InfluxDB JavaScript client library +seotitle: Install the InfluxDB Node.js JavaScript client library +description: > + Install the JavaScript client library to interact with the InfluxDB API in Node.js. +menu: + influxdb_2_1: + name: Install + parent: Node.js +influxdb/v2.1/tags: [client libraries, JavaScript] +weight: 100 +aliases: + - /influxdb/v2.1/reference/api/client-libraries/nodejs/install +--- + + +## Install Node.js + +1. Install [Node.js](https://nodejs.org/en/download/package-manager/). + +2. Ensure that InfluxDB is running and you can connect to it. + For information about what URL to use to connect to InfluxDB OSS or InfluxDB Cloud, see [InfluxDB URLs](/influxdb/v2.1/reference/urls/). + +3. Start a new Node.js project. + The `npm` package manager is included with Node.js. + + ```sh + npm init -y influx-node-app + ``` + +## Install TypeScript + +Many of the client library examples use [TypeScript](https://www.typescriptlang.org/). Follow these steps to initialize the TypeScript project. + +1. Install TypeScript and type definitions for Node.js. + + ```sh + npm i -g typescript && npm i --save-dev @types/node + ``` +2. Create a TypeScript configuration with default values. + + ```sh + tsc --init + ``` +3. Run the TypeScript compiler. To recompile your code automatically as you make changes, pass the `watch` flag to the compiler. + + ```sh + tsc -w -p + ``` + +## Install dependencies + +The JavaScript client library contains two packages: `@influxdata/influxdb-client` and `@influxdata/influxdb-client-apis`. +Add both as dependencies of your project. + +1. Open a new terminal window and install `@influxdata/influxdb-client` for querying and writing data: + + ```sh + npm install --save @influxdata/influxdb-client + ``` + +3. Install `@influxdata/influxdb-client-apis` for access to the InfluxDB management APIs: + + ```sh + npm install --save @influxdata/influxdb-client-apis + ``` + +## Next steps + +Once you've installed the Javascript client library, you're ready to [write data](/influxdb/v2.1/api-guide/client-libraries/nodejs/write/) to InfluxDB or [get started](#get-started-with-examples) with other examples from the client library. + +## Get started with examples + +{{% note %}} +The client examples include an [`env`](https://github.com/influxdata/influxdb-client-js/blob/master/examples/env.js) module for accessing your InfluxDB properties from environment variables or from `env.js`. +The examples use these properties to interact with the InfluxDB API. +{{% /note %}} + +1. Set environment variables or update `env.js` with your InfluxDB [bucket](/influxdb/v2.1/organizations/buckets/), [organization](/influxdb/v2.1/organizations/), [token](/influxdb/v2.1/security/tokens/), and [url](/influxdb/v2.1/reference/urls/). + + ```sh + export INFLUX_URL=http://localhost:8086 + export INFLUX_TOKEN=YOUR_API_TOKEN + export INFLUX_ORG=YOUR_ORG + export INFLUX_BUCKET=YOUR_BUCKET + ``` + Replace the following: + - *`YOUR_API_TOKEN`*: InfluxDB API token + - *`YOUR_ORG`*: InfluxDB organization ID + - *`YOUR_BUCKET`*: InfluxDB bucket name + +2. Run an example script. + + ```sh + query.ts + ``` +{{% api/v2dot0/nodejs/learn-more %}} diff --git a/content/influxdb/v2.1/api-guide/client-libraries/nodejs/query.md b/content/influxdb/v2.1/api-guide/client-libraries/nodejs/query.md new file mode 100644 index 0000000000..3bf47bc7c7 --- /dev/null +++ b/content/influxdb/v2.1/api-guide/client-libraries/nodejs/query.md @@ -0,0 +1,94 @@ +--- +title: Query data with the InfluxDB JavaScript client library +description: > + Use the JavaScript client library to query data with the InfluxDB API in Node.js. +menu: + influxdb_2_1: + name: Query + parent: Node.js +influxdb/v2.1/tags: [client libraries, JavaScript] +weight: 201 +aliases: + - /influxdb/v2.1/reference/api/client-libraries/nodejs/query +--- + +Use the [InfluxDB JavaScript client library](https://github.com/influxdata/influxdb-client-js) in a Node.js environment to query InfluxDB. + +The following example sends a Flux query to an InfluxDB bucket and outputs rows from an observable table. + +## Before you begin + +- [Install the client library and other dependencies](/influxdb/v2.1/api-guide/client-libraries/nodejs/install/). + +## Query InfluxDB + +1. Change to your new project directory and create a file for your query module. + + ```sh + cd influx-node-app && touch query.js + ``` + +2. Instantiate an `InfluxDB` client. Provide your InfluxDB URL and API token. + Use the `getQueryApi()` method of the client. + Provide your InfluxDB organization ID to create a configured **query client**. + + ```js + import { InfluxDB, Point } from '@influxdata/influxdb-client' + + const queryApi = new InfluxDB({YOUR_URL, YOUR_API_TOKEN}).getQueryApi(YOUR_ORG) + ``` + + Replace the following: + - *`YOUR_URL`*: InfluxDB URL + - *`YOUR_API_TOKEN`*: InfluxDB API token + - *`YOUR_ORG`*: InfluxDB organization ID + +3. Create a Flux query for your InfluxDB bucket. Store the query as a string variable. + {{% warn %}} + To prevent SQL injection attacks, avoid concatenating unsafe user input with queries. + {{% /warn %}} + + ```js + const fluxQuery = + 'from(bucket: "YOUR_BUCKET") + |> range(start: 0) + |> filter(fn: (r) => r._measurement == "temperature")' + ``` + Replace *`YOUR_BUCKET`* with the name of your InfluxDB bucket. + +4. Use the `queryRows()` method of the query client to query InfluxDB. + `queryRows()` takes a Flux query and an [RxJS **Observer**](http://reactivex.io/rxjs/manual/overview.html#observer) object. + The client returns [table](/{{% latest "influxdb" %}}/reference/syntax/annotated-csv/#tables) metadata and rows as an [RxJS **Observable**](http://reactivex.io/rxjs/manual/overview.html#observable). + `queryRows()` subscribes your observer to the observable. + Finally, the observer logs the rows from the response to the terminal. + + ```js + const observer = { + next(row, tableMeta) { + const o = tableMeta.toObject(row) + console.log( + `${o._time} ${o._measurement} in '${o.location}' (${o.sensor_id}): ${o._field}=${o._value}` + ) + } + } + + queryApi.queryRows(fluxQuery, observer) + + ``` + +### Complete example + +```js +{{% get-shared-text "api/v2.0/query/query.mjs" %}} +``` + +To run the example from a file, set your InfluxDB environment variables and use `node` to execute the JavaScript file. + +```sh +export INFLUX_URL=http://localhost:8086 && \ +export INFLUX_TOKEN=YOUR_API_TOKEN && \ +export INFLUX_ORG=YOUR_ORG && \ +node query.js +``` + +{{% api/v2dot0/nodejs/learn-more %}} diff --git a/content/influxdb/v2.1/api-guide/client-libraries/nodejs/write.md b/content/influxdb/v2.1/api-guide/client-libraries/nodejs/write.md new file mode 100644 index 0000000000..a441a21946 --- /dev/null +++ b/content/influxdb/v2.1/api-guide/client-libraries/nodejs/write.md @@ -0,0 +1,117 @@ +--- +title: Write data with the InfluxDB JavaScript client library +description: > + Use the JavaScript client library to write data with the InfluxDB API in Node.js. +menu: + influxdb_2_1: + name: Write + parent: Node.js +influxdb/v2.1/tags: [client libraries, JavaScript] +weight: 101 +aliases: + - /influxdb/v2.1/reference/api/client-libraries/nodejs/write +related: + - /influxdb/v2.1/write-data/troubleshoot/ +--- + +Use the [InfluxDB Javascript client library](https://github.com/influxdata/influxdb-client-js) to write data from a Node.js environment to InfluxDB. + +The Javascript client library includes the following convenient features for writing data to InfluxDB: +- Apply default tags to data points. +- Buffer points into batches to optimize data transfer. +- Automatically retry requests on failure. +- Set an optional HTTP proxy address for your network. + +### Before you begin + +- [Install the client library and other dependencies](/influxdb/v2.1/api-guide/client-libraries/nodejs/install/). +### Write data with the client library + +1. Instantiate an `InfluxDB` client. Provide your InfluxDB URL and API token. + + ```js + import {InfluxDB, Point} from '@influxdata/influxdb-client' + + const influxDB = new InfluxDB({YOUR_URL, YOUR_API_TOKEN}) + ``` + Replace the following: + - *`YOUR_URL`*: InfluxDB URL + - *`YOUR_API_TOKEN`*: InfluxDB API token + +2. Use the `getWriteApi()` method of the client to create a **write client**. + Provide your InfluxDB organization ID and bucket name. + + ```js + const writeApi = influxDB.getWriteApi(YOUR_ORG, YOUR_BUCKET) + ``` + Replace the following: + - *`YOUR_ORG`*: InfluxDB organization ID + - *`YOUR_BUCKET`*: InfluxDB bucket name + +3. To apply one or more [tags](/influxdb/v2.1/reference/glossary/#tag) to all points, use the `useDefaultTags()` method. + Provide tags as an object of key/value pairs. + + ```js + writeApi.useDefaultTags({region: 'west'}) + ``` + +4. Use the `Point()` constructor to create a [point](/influxdb/v2.1/reference/glossary/#point). + 1. Call the constructor and provide a [measurement](/influxdb/v2.1/reference/glossary/#measurement). + 2. To add one or more tags, chain the `tag()` method to the constructor. + Provide a `name` and `value`. + 3. To add a field of type `float`, chain the `floatField()` method to the constructor. + Provide a `name` and `value`. + + ```js + const point1 = new Point('temperature') + .tag('sensor_id', 'TLM010') + .floatField('value', 24) + ``` + +5. Use the `writePoint()` method to write the point to your InfluxDB bucket. + Finally, use the `close()` method to flush all pending writes. + The example logs the new data point followed by "WRITE FINISHED" to stdout. + + ```js + writeApi.writePoint(point1) + + writeApi.close().then(() => { + console.log('WRITE FINISHED') + }) + ``` + +### Complete example + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Curl](#curl) +[Node.js](#nodejs) +{{% /code-tabs %}} +{{% code-tab-content %}} + +```sh +{{< get-shared-text "api/v2.0/write/write.sh" >}} +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + +```js +{{< get-shared-text "api/v2.0/write/write.mjs" >}} +``` + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +To run the example from a file, set your InfluxDB environment variables and use `node` to execute the JavaScript file. + +```sh +export INFLUX_URL=http://localhost:8086 && \ +export INFLUX_TOKEN=YOUR_API_TOKEN && \ +export INFLUX_ORG=YOUR_ORG && \ +export INFLUX_BUCKET=YOUR_BUCKET && \ +node write.js +``` + +### Response codes +_For information about **InfluxDB API response codes**, see +[InfluxDB API Write documentation](/influxdb/cloud/api/#operation/PostWrite)._ diff --git a/content/influxdb/v2.1/api-guide/client-libraries/php.md b/content/influxdb/v2.1/api-guide/client-libraries/php.md new file mode 100644 index 0000000000..cf263dcb50 --- /dev/null +++ b/content/influxdb/v2.1/api-guide/client-libraries/php.md @@ -0,0 +1,13 @@ +--- +title: PHP client library +seotitle: Use the InfluxDB PHP client library +list_title: PHP +description: Use the InfluxDB PHP client library to interact with InfluxDB. +external_url: https://github.com/influxdata/influxdb-client-php +menu: + influxdb_2_1: + name: PHP + parent: Client libraries + url: https://github.com/influxdata/influxdb-client-php +weight: 201 +--- diff --git a/content/influxdb/v2.1/api-guide/client-libraries/python.md b/content/influxdb/v2.1/api-guide/client-libraries/python.md new file mode 100644 index 0000000000..5d5acdcbb9 --- /dev/null +++ b/content/influxdb/v2.1/api-guide/client-libraries/python.md @@ -0,0 +1,176 @@ +--- +title: Python client library +seotitle: Use the InfluxDB Python client library +list_title: Python +description: > + Use the InfluxDB Python client library to interact with InfluxDB. +menu: + influxdb_2_1: + name: Python + parent: Client libraries +influxdb/v2.1/tags: [client libraries, python] +aliases: + - /influxdb/v2.1/reference/api/client-libraries/python/ + - /influxdb/v2.1/reference/api/client-libraries/python-cl-guide/ + - /influxdb/v2.1/tools/client-libraries/python/ +weight: 201 +--- + +Use the [InfluxDB Python client library](https://github.com/influxdata/influxdb-client-python) to integrate InfluxDB into Python scripts and applications. + +This guide presumes some familiarity with Python and InfluxDB. +If just getting started, see [Get started with InfluxDB](/influxdb/v2.1/get-started/). + +## Before you begin + +1. Install the InfluxDB Python library: + + ```sh + pip install influxdb-client + ``` + +2. Ensure that InfluxDB is running. + If running InfluxDB locally, visit http://localhost:8086. + (If using InfluxDB Cloud, visit the URL of your InfluxDB Cloud UI. + For example: https://us-west-2-1.aws.cloud2.influxdata.com.) + +## Write data to InfluxDB with Python + +We are going to write some data in [line protocol](/influxdb/v2.1/reference/syntax/line-protocol/) using the Python library. + +1. In your Python program, import the InfluxDB client library and use it to write data to InfluxDB. + + ```python + import influxdb_client + from influxdb_client.client.write_api import SYNCHRONOUS + ``` + +2. Define a few variables with the name of your [bucket](/influxdb/v2.1/organizations/buckets/), [organization](/influxdb/v2.1/organizations/), and [token](/influxdb/v2.1/security/tokens/). + + ```python + bucket = "" + org = "" + token = "" + # Store the URL of your InfluxDB instance + url="http://localhost:8086" + ``` + +3. Instantiate the client. The `InfluxDBClient` object takes three named parameters: `url`, `org`, and `token`. Pass in the named parameters. + + ```python + client = influxdb_client.InfluxDBClient( + url=url, + token=token, + org=org + ) + ``` + The `InfluxDBClient` object has a `write_api` method used for configuration. + +4. Instantiate a **write client** using the `client` object and the `write_api` method. Use the `write_api` method to configure the writer object. + + ```python + write_api = client.write_api(write_options=SYNCHRONOUS) + ``` + +5. Create a [point](/influxdb/v2.1/reference/glossary/#point) object and write it to InfluxDB using the `write` method of the API writer object. The write method requires three parameters: `bucket`, `org`, and `record`. + + ```python + p = influxdb_client.Point("my_measurement").tag("location", "Prague").field("temperature", 25.3) + write_api.write(bucket=bucket, org=org, record=p) + ``` + +### Complete example write script + +```python +import influxdb_client +from influxdb_client.client.write_api import SYNCHRONOUS + +bucket = "" +org = "" +token = "" +# Store the URL of your InfluxDB instance +url="http://localhost:8086" + +client = influxdb_client.InfluxDBClient( + url=url, + token=token, + org=org +) + +write_api = client.write_api(write_options=SYNCHRONOUS) + +p = influxdb_client.Point("my_measurement").tag("location", "Prague").field("temperature", 25.3) +write_api.write(bucket=bucket, org=org, record=p) +``` +## Query data from InfluxDB with Python + +1. Instantiate the **query client**. + + ```python + query_api = client.query_api() + ``` + +2. Create a Flux query. + + ```python + query = ‘ from(bucket:"my-bucket")\ + |> range(start: -10m)\ + |> filter(fn:(r) => r._measurement == "my_measurement")\ + |> filter(fn: (r) => r.location == "Prague")\ + |> filter(fn:(r) => r._field == "temperature" )‘ + ``` + + The query client sends the Flux query to InfluxDB and returns a Flux object with a table structure. + +3. Pass the `query()` method two named parameters:`org` and `query`. + + ```python + result = query_api.query(org=org, query=query) + ``` + +4. Iterate through the tables and records in the Flux object. + - Use the `get_value()` method to return values. + - Use the `get_field()` method to return fields. + + ```python + results = [] + for table in result: + for record in table.records: + results.append((record.get_field(), record.get_value())) + + print(results) + [(temperature, 25.3)] + ``` + +**The Flux object provides the following methods for accessing your data:** + +- `get_measurement()`: Returns the measurement name of the record. +- `get_field()`: Returns the field name. +- `get_value()`: Returns the actual field value. +- `values`: Returns a map of column values. +- `values.get("")`: Returns a value from the record for given column. +- `get_time()`: Returns the time of the record. +- `get_start()`: Returns the inclusive lower time bound of all records in the current table. +- `get_stop()`: Returns the exclusive upper time bound of all records in the current table. + + +### Complete example query script + +```python +query_api = client.query_api() +query = ‘ from(bucket:"my-bucket")\ +|> range(start: -10m)\ +|> filter(fn:(r) => r._measurement == "my_measurement")\ +|> filter(fn: (r) => r.location == "Prague")\ +|> filter(fn:(r) => r._field == "temperature" )‘ +result = query_api.query(org=org, query=query) +results = [] +for table in result: + for record in table.records: + results.append((record.get_field(), record.get_value())) + +print(results) +[(temperature, 25.3)] +``` + +For more information, see the [Python client README on GitHub](https://github.com/influxdata/influxdb-client-python). diff --git a/content/influxdb/v2.1/api-guide/client-libraries/r.md b/content/influxdb/v2.1/api-guide/client-libraries/r.md new file mode 100644 index 0000000000..20685100ef --- /dev/null +++ b/content/influxdb/v2.1/api-guide/client-libraries/r.md @@ -0,0 +1,13 @@ +--- +title: R package client library +list_title: R +seotitle: Use the InfluxDB client R package +description: Use the InfluxDB client R package to interact with InfluxDB. +external_url: https://github.com/influxdata/influxdb-client-r +menu: + influxdb_2_1: + name: R + parent: Client libraries + url: https://github.com/influxdata/influxdb-client-r +weight: 201 +--- diff --git a/content/influxdb/v2.1/api-guide/client-libraries/ruby.md b/content/influxdb/v2.1/api-guide/client-libraries/ruby.md new file mode 100644 index 0000000000..e38ff20820 --- /dev/null +++ b/content/influxdb/v2.1/api-guide/client-libraries/ruby.md @@ -0,0 +1,13 @@ +--- +title: Ruby client library +seotitle: Use the InfluxDB Ruby client library +list_title: Ruby +description: Use the InfluxDB Ruby client library to interact with InfluxDB. +external_url: https://github.com/influxdata/influxdb-client-ruby +menu: + influxdb_2_1: + name: Ruby + parent: Client libraries + url: https://github.com/influxdata/influxdb-client-ruby +weight: 201 +--- diff --git a/content/influxdb/v2.1/api-guide/client-libraries/scala.md b/content/influxdb/v2.1/api-guide/client-libraries/scala.md new file mode 100644 index 0000000000..96c22f7be5 --- /dev/null +++ b/content/influxdb/v2.1/api-guide/client-libraries/scala.md @@ -0,0 +1,13 @@ +--- +title: Scala client library +seotitle: Use the InfluxDB Scala client library +list_title: Scala +description: Use the InfluxDB Scala client library to interact with InfluxDB. +external_url: https://github.com/influxdata/influxdb-client-java/tree/master/client-scala +menu: + influxdb_2_1: + name: Scala + parent: Client libraries + url: https://github.com/influxdata/influxdb-client-java/tree/master/client-scala +weight: 201 +--- diff --git a/content/influxdb/v2.1/api-guide/client-libraries/swift.md b/content/influxdb/v2.1/api-guide/client-libraries/swift.md new file mode 100644 index 0000000000..420a2f2286 --- /dev/null +++ b/content/influxdb/v2.1/api-guide/client-libraries/swift.md @@ -0,0 +1,13 @@ +--- +title: Swift client library +seotitle: Use the InfluxDB Swift client library +list_title: Swift +description: Use the InfluxDB Swift client library to interact with InfluxDB. +external_url: https://github.com/influxdata/influxdb-client-swift +menu: + influxdb_2_1: + name: Swift + parent: Client libraries + url: https://github.com/influxdata/influxdb-client-swift +weight: 201 +--- diff --git a/content/influxdb/v2.1/api-guide/postman.md b/content/influxdb/v2.1/api-guide/postman.md new file mode 100644 index 0000000000..dd6ac7fdab --- /dev/null +++ b/content/influxdb/v2.1/api-guide/postman.md @@ -0,0 +1,48 @@ +--- +title: Use Postman with the InfluxDB API +description: > + Use [Postman](https://www.postman.com/), a popular tool for exploring APIs, + to interact with the [InfluxDB API](/influxdb/v2.1/reference/api). +menu: + influxdb_2_1: + parent: Tools & integrations + name: Use Postman +weight: 105 +influxdb/v2.1/tags: [api, authentication] +aliases: + - /influxdb/v2.1/reference/api/postman/ +--- + +Use [Postman](https://www.postman.com/), a popular tool for exploring APIs, +to interact with the [InfluxDB API](/influxdb/v2.1/reference/api). + +## Install Postman + +Download Postman from the [official downloads page](https://www.postman.com/downloads/). + +Or to install with Homebrew on macOS, run the following command: + +```sh +brew cask install postman +``` + +## Send authenticated API requests with Postman + +All requests to the InfluxDB API must be authenticated. +Postman lets you configure the headers and body of HTTP requests. + +Use the **Authorization** tab in Postman to include the credentials required when interacting with the InfluxDB API. + +1. If you have not already, [create a token](/influxdb/v2.1/security/tokens/create-token/). +2. In the **Authorization** tab, select **API Key** in the **Type** dropdown. +3. For **Key**, enter `Authorization`. +4. For **Value**, enter `Token `, replacing `` with the token generated in step 1. +5. Ensure that the **Add to** option is set to **Header**. + +#### Test authentication credentials +To test the authentication, enter the root endpoint of an InfluxDB OSS instance URL and click **Send**. + +###### InfluxDB API endpoint +```sh +http://localhost:8086/api/v2 +``` diff --git a/content/influxdb/v2.1/backup-restore/_index.md b/content/influxdb/v2.1/backup-restore/_index.md new file mode 100644 index 0000000000..306277d5ce --- /dev/null +++ b/content/influxdb/v2.1/backup-restore/_index.md @@ -0,0 +1,17 @@ +--- +title: Back up and restore data +seotitle: Backup and restore data with InfluxDB +description: > + InfluxDB provides tools that let you back up and restore data and metadata stored + in InfluxDB. +influxdb/v2.1/tags: [backup, restore] +menu: + influxdb_2_1: + name: Back up & restore data +weight: 9 +products: [oss] +--- + +InfluxDB provides tools to back up and restore data and metadata stored in InfluxDB. + +{{< children >}} diff --git a/content/influxdb/v2.1/backup-restore/backup.md b/content/influxdb/v2.1/backup-restore/backup.md new file mode 100644 index 0000000000..7d403945a6 --- /dev/null +++ b/content/influxdb/v2.1/backup-restore/backup.md @@ -0,0 +1,49 @@ +--- +title: Back up data +seotitle: Back up data in InfluxDB +description: > + Use the `influx backup` command to back up data and metadata stored in InfluxDB. +menu: + influxdb_2_1: + parent: Back up & restore data +weight: 101 +related: + - /influxdb/v2.1/backup-restore/restore/ + - /influxdb/v2.1/reference/cli/influx/backup/ +products: [oss] +--- + +Use the [`influx backup` command](/influxdb/v2.1/reference/cli/influx/backup/) to back up +data and metadata stored in InfluxDB. +InfluxDB copies all data and metadata to a set of files stored in a specified directory +on your local filesystem. + +{{% note %}} +#### InfluxDB 1.x/2.1 compatibility +The InfluxDB {{< current-version >}} `influx backup` command is not compatible with versions of InfluxDB prior to 2.0.0. +**For information about migrating data between InfluxDB 1.x and {{< current-version >}}, see:** + +- [Automatically upgrade from InfluxDB 1.x to {{< current-version >}}](/influxdb/v2.1/upgrade/v1-to-v2/automatic-upgrade/) +- [Manually upgrade from InfluxDB 1.x to {{< current-version >}}](/influxdb/v2.1/upgrade/v1-to-v2/manual-upgrade/) +{{% /note %}} + +{{% cloud %}} +The `influx backup` command **cannot** back up data stored in **{{< cloud-name "short" >}}**. +{{% /cloud %}} + +The `influx backup` command requires: + +- The directory path for where to store the backup file set +- The **root authorization token** (the token created for the first user in the + [InfluxDB setup process](/influxdb/v2.1/get-started/)). + +##### Back up data with the influx CLI +```sh +# Syntax +influx backup -t + +# Example +influx backup \ + path/to/backup_$(date '+%Y-%m-%d_%H-%M') \ + -t xXXXX0xXX0xxX0xx_x0XxXxXXXxxXX0XXX0XXxXxX0XxxxXX0Xx0xx== +``` diff --git a/content/influxdb/v2.1/backup-restore/restore.md b/content/influxdb/v2.1/backup-restore/restore.md new file mode 100644 index 0000000000..d623b02645 --- /dev/null +++ b/content/influxdb/v2.1/backup-restore/restore.md @@ -0,0 +1,141 @@ +--- +title: Restore data +seotitle: Restore data in InfluxDB +description: > + Use the `influxd restore` command to restore backup data and metadata from InfluxDB. +menu: + influxdb_2_1: + parent: Back up & restore data +weight: 101 +influxdb/v2.1/tags: [restore] +related: + - /influxdb/v2.1/backup-restore/backup/ + - /influxdb/v2.1/reference/cli/influxd/restore/ +products: [oss] +--- + +{{% cloud %}} +Restores **not supported in {{< cloud-name "short" >}}**. +{{% /cloud %}} + +Use the `influx restore` command to restore backup data and metadata from InfluxDB OSS. + +- [Restore data with the influx CLI](#restore-data-with-the-influx-cli) +- [Recover from a failed restore](#recover-from-a-failed-restore) + +InfluxDB moves existing data and metadata to a temporary location. +If the restore fails, InfluxDB preserves temporary data for recovery, +otherwise this data is deleted. +_See [Recover from a failed restore](#recover-from-a-failed-restore)._ + +{{% note %}} +#### Cannot restore to existing buckets +The `influx restore` command cannot restore data to existing buckets. +Use the `--new-bucket` flag to create a new bucket to restore data to. +To restore data and retain bucket names, [delete existing buckets](/influxdb/v2.1/organizations/buckets/delete-bucket/) +and then begin the restore process. +{{% /note %}} + +## Restore data with the influx CLI +Use the `influx restore` command and specify the path to the backup directory. + +_For more information about restore options and flags, see the +[`influx restore` documentation](/influxdb/v2.1/reference/cli/influx/restore/)._ + +- [Restore all time series data](#restore-all-time-series-data) +- [Restore data from a specific bucket](#restore-data-from-a-specific-bucket) +- [Restore and replace all InfluxDB data](#restore-and-replace-all-influxdb-data) + +### Restore all time series data +To restore all time series data from a backup directory, provide the following: + +- backup directory path + +```sh +influx restore /backups/2020-01-20_12-00/ +``` + +### Restore data from a specific bucket +To restore data from a specific backup bucket, provide the following: + +- backup directory path +- bucket name or ID + +```sh +influx restore \ + /backups/2020-01-20_12-00/ \ + --bucket example-bucket + +# OR + +influx restore \ + /backups/2020-01-20_12-00/ \ + --bucket-id 000000000000 +``` + +If a bucket with the same name as the backed up bucket already exists in InfluxDB, +use the `--new-bucket` flag to create a new bucket with a different name and +restore data into it. + +```sh +influx restore \ + /backups/2020-01-20_12-00/ \ + --bucket example-bucket \ + --new-bucket new-example-bucket +``` + +### Restore and replace all InfluxDB data +To restore and replace all time series data _and_ InfluxDB key-value data such as +tokens, users, dashboards, etc., include the following: + +- `--full` flag +- backup directory path + +```sh +influx restore \ + /backups/2020-01-20_12-00/ \ + --full +``` + +{{% note %}} +#### Restore to a new InfluxDB server +If using a backup to populate a new InfluxDB server: + +1. Retrieve the [admin token](/influxdb/v2.1/security/tokens/#admin-token) from your source InfluxDB instance. +2. Set up your new InfluxDB instance, but use the `-t`, `--token` flag to use the + **admin token** from your source instance as the admin token on your new instance. + + ```sh + influx setup --token My5uP3rSecR37t0keN + ``` +3. Restore the backup to the new server. + + ```sh + influx restore \ + /backups/2020-01-20_12-00/ \ + --full + ``` + +If you do not provide the admin token from your source InfluxDB instance as the +admin token in your new instance, the restore process and all subsequent attempts +to authenticate with the new server will fail. + +1. The first restore API call uses the auto-generated token to authenticate with + the new server and overwrites the entire key-value store in the new server, including + the auto-generated token. +2. The second restore API call attempts to upload time series data, but uses the + auto-generated token to authenticate with new server. + That token is overwritten in first restore API call and the process fails to authenticate. +{{% /note %}} + + +## Recover from a failed restore +If the restoration process fails, InfluxDB preserves existing data in a `tmp` +directory in the [target engine path](/influxdb/v2.1/reference/cli/influx/restore/#flags) +(default is `~/.influxdbv2/engine`). + +To recover from a failed restore: + +1. Copy the temporary files back into the `engine` directory. +2. Remove the `.tmp` extensions from each of the copied files. +3. Restart the `influxd` server. diff --git a/content/influxdb/v2.1/get-started.md b/content/influxdb/v2.1/get-started.md new file mode 100644 index 0000000000..d55c5de33a --- /dev/null +++ b/content/influxdb/v2.1/get-started.md @@ -0,0 +1,59 @@ +--- +title: Get started with InfluxDB +description: > + Start collecting, processing, and visualizing data in InfluxDB OSS. +menu: + influxdb_2_1: + name: Get started +weight: 3 +influxdb/v2.1/tags: [get-started] +aliases: + - /influxdb/v2.1/introduction/get-started/ +--- + +After you've [installed InfluxDB OSS](/influxdb/v2.1/install/), you're ready to get started. Explore the following ways to work with your data: + +- [Collect and write data](#collect-and-write-data) +- [Query data](#query-data) +- [Process data](#process-data) +- [Visualize data](#visualize-data) +- [Monitor and alert](#monitor-and-alert) + +### Collect and write data + +Collect and write data to InfluxDB using the Telegraf plugins, the InfluxDB v2 API, the `influx` command line interface (CLI), the InfluxDB UI (the user interface for InfluxDB 2.1), or the InfluxDB v2 API client libraries. + +#### Use Telegraf + +Use Telegraf to quickly write data to {{< cloud-name >}}. +Create new Telegraf configurations automatically in the InfluxDB UI, or manually update an existing Telegraf configuration to send data to your {{< cloud-name "short" >}} instance. + +For details, see [Automatically configure Telegraf](/influxdb/v2.1/write-data/no-code/use-telegraf/auto-config/) +and [Manually update Telegraf configurations](/influxdb/v2.1/write-data/no-code/use-telegraf/manual-config/). + +#### Scrape data + +**InfluxDB OSS** lets you scrape Prometheus-formatted metrics from HTTP endpoints. For details, see [Scrape data](/influxdb/v2.1/write-data/no-code/scrape-data/). + +#### API, CLI, and client libraries + +For information about using the InfluxDB v2 API, `influx` CLI, and client libraries to write data, see [Write data to InfluxDB](/influxdb/v2.1/write-data/). + +### Query data + +Query data using Flux, the UI, and the `influx` command line interface. +See [Query data](/influxdb/v2.1/query-data/). + +### Process data + +Use InfluxDB tasks to process and downsample data. See [Process data](/influxdb/v2.1/process-data/). + +### Visualize data + +Build custom dashboards to visualize your data. +See [Visualize data](/influxdb/v2.1/visualize-data/). + +### Monitor and alert + +Monitor your data and sends alerts based on specified logic. +See [Monitor and alert](/influxdb/v2.1/monitor-alert/). diff --git a/content/influxdb/v2.1/influxdb-templates/_index.md b/content/influxdb/v2.1/influxdb-templates/_index.md new file mode 100644 index 0000000000..982ad31c88 --- /dev/null +++ b/content/influxdb/v2.1/influxdb-templates/_index.md @@ -0,0 +1,74 @@ +--- +title: InfluxDB templates +description: > + InfluxDB templates are preconfigured InfluxDB resources and can contain everything + from dashboards and Telegraf configurations to notifications and alerts. +menu: influxdb_2_1 +weight: 9 +influxdb/v2.1/tags: [templates] +--- + +InfluxDB templates are preconfigured InfluxDB resources and can contain everything +from dashboards and Telegraf configurations to notifications and alerts. +Use InfluxDB templates to quickly get set up monitoring a specific technology, +set up a fresh instance of InfluxDB, back up your dashboard configuration, or +[share your configuration](https://github.com/influxdata/community-templates/) with the InfluxData community. + +**InfluxDB templates do the following:** + +- Reduce setup time by giving you resources that are already configured for your use-case. +- Facilitate secure, portable, and source-controlled InfluxDB resource states. +- Simplify sharing and using pre-built InfluxDB solutions. + +{{< youtube 2JjW4Rym9XE >}} + +View InfluxDB community templates + +## Template manifests + +A template consists of one or more files known as **manifests** that define the +InfluxDB [resources](#template-resources). +Template manifests support the following formats: + +- [YAML](https://yaml.org/) +- [JSON](https://www.json.org/) +- [Jsonnet](https://jsonnet.org/) + +{{% note %}} +Template manifests are compatible with +[Kubernetes Custom Resource Definitions (CRD)](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/). +{{% /note %}} + +The `metadata.name` field in manifests uniquely identifies each resource in the template. +`metadata.name` values must be [DNS-1123](https://tools.ietf.org/html/rfc1123) compliant. +If resources in the template depend on other InfluxDB resources, all dependencies +should be included in the template, otherwise, the resources may not be usable. + +_See [Create an InfluxDB template](/influxdb/v2.1/influxdb-templates/create/) for information about +generating template manifests._ + +### Template resources + +Include the following **resources** in a template: + +- buckets +- checks +- dashboards +- dashboard variables +- labels +- notification endpoints +- notification rules +- tasks +- Telegraf configurations + +## Stacks + +Use **InfluxDB stacks** to manage InfluxDB templates. +When you apply a template, InfluxDB associates resources in the template with a stack. +Use stacks to add, update, or remove InfluxDB templates over time. + +For more information, see [InfluxDB stacks](#influxdb-stacks) below. + +--- + +{{< children >}} diff --git a/content/influxdb/v2.1/influxdb-templates/create.md b/content/influxdb/v2.1/influxdb-templates/create.md new file mode 100644 index 0000000000..8539997c7d --- /dev/null +++ b/content/influxdb/v2.1/influxdb-templates/create.md @@ -0,0 +1,263 @@ +--- +title: Create an InfluxDB template +description: > + Use the InfluxDB UI and the `influx export` command to create InfluxDB templates. +menu: + influxdb_2_1: + parent: InfluxDB templates + name: Create a template + identifier: Create an InfluxDB template +weight: 103 +influxdb/v2.1/tags: [templates] +related: + - /influxdb/v2.1/reference/cli/influx/export/ + - /influxdb/v2.1/reference/cli/influx/export/all/ +--- + +Use the InfluxDB user interface (UI) and the `influx export` command to +create InfluxDB templates. +Add resources (buckets, Telegraf configurations, tasks, and more) in the InfluxDB +UI and export the resources as a template. + +{{< youtube 714uHkxKM6U >}} + +{{% note %}} +Templatable resources are scoped to a single organization, so the simplest way to create a +template is to create a new organization, build the template within the organization, +and then [export all resources](#export-all-resources) as a template. +{{% /note %}} + +**To create a template:** + +1. [Start InfluxDB](/influxdb/v2.1/get-started/). +2. [Create a new organization](/influxdb/v2.1/organizations/create-org/). +3. In the InfluxDB UI add one or more of the following templatable resources: + + - [buckets](/influxdb/v2.1/organizations/buckets/create-bucket/) + - [checks](/influxdb/v2.1/monitor-alert/checks/create/) + - [dashboards](/influxdb/v2.1/visualize-data/dashboards/create-dashboard/) + - [dashboard variables](/influxdb/v2.1/visualize-data/variables/create-variable/) + - [labels](/influxdb/v2.1/visualize-data/labels/) + - [notification endpoints](/influxdb/v2.1/monitor-alert/notification-endpoints/create/) + - [notification rules](/influxdb/v2.1/monitor-alert/notification-rules/create/) + - [tasks](/influxdb/v2.1/process-data/manage-tasks/create-task/) + - [Telegraf configurations](/influxdb/v2.1/write-data/no-code/use-telegraf/) + +4. Export the template _(see [below](#export-a-template))_. + +## Export a template + +Do one of the following to export a template: + +- [Export all resources in an organization](#export-all-resources) +- [Export specific resources in an organization](#export-specific-resources) +- [Export a stack and its associated resources](#export-a-stack) + +### Export all resources + +To export all templatable resources within an organization to a template manifest, +use the `influx export all` command. +Provide the following: + +- **Organization name** or **ID** +- **API token** with read access to the organization +- **Destination path and filename** for the template manifest. + The filename extension determines the template format—both **YAML** (`.yml`) and + **JSON** (`.json`) are supported. + +###### Export all resources to a template + +```sh +# Syntax +influx export all -o -f -t + +# Example +influx export all \ + -o my-org \ + -f ~/templates/awesome-template.yml \ + -t $INFLUX_TOKEN +``` + +#### Export resources filtered by labelName or resourceKind + +The `influx export all` command has an optional `--filter` flag that exports +only resources that match specified label names or resource kinds. +Provide multiple filters for both `labelName` and `resourceKind`. + +###### Export only dashboards and buckets with specific labels + +The following example exports resources that match this predicate logic: + +```js +(resourceKind == "Bucket" or resourceKind == "Dashboard") +and +(labelName == "Example1" or labelName == "Example2") +``` + +```sh +influx export all \ + -o my-org \ + -f ~/templates/awesome-template.yml \ + -t $INFLUX_TOKEN \ + --filter=resourceKind=Bucket \ + --filter=resourceKind=Dashboard \ + --filter=labelName=Example1 \ + --filter=labelName=Example2 +``` + +For information about flags, see the +[`influx export all` documentation](/influxdb/v2.1/reference/cli/influx/export/all/). + +### Export specific resources + +To export specific resources within an organization to a template manifest, use the `influx export` with resource flags for each resource to include. +Provide the following: + +- **Organization name** or **ID** +- **API token** with read access to the organization +- **Destination path and filename** for the template manifest. + The filename extension determines the template format—both **YAML** (`.yml`) and + **JSON** (`.json`) are supported. +- **Resource flags** with corresponding lists of resource IDs or resource names to include in the template. + For information about what resource flags are available, see the + [`influx export` documentation](/influxdb/v2.1/reference/cli/influx/export/). + +###### Export specific resources to a template + +```sh +# Syntax +influx export all -o -f -t [resource-flags] + +# Export specific resources by ID +influx export all \ + -o my-org \ + -f ~/templates/awesome-template.yml \ + -t $INFLUX_TOKEN \ + --buckets=00x000ooo0xx0xx,o0xx0xx00x000oo \ + --dashboards=00000xX0x0X00x000 \ + --telegraf-configs=00000x0x000X0x0X0 + +# Export specific resources by name +influx export all \ + -o my-org \ + -f ~/templates/awesome-template.yml \ + -t $INFLUX_TOKEN \ + --bucket-names=bucket1,bucket2 \ + --dashboard-names=dashboard1,dashboard2 \ + --telegraf-config-names=telegrafconfig1,telegrafconfig2 +``` + +### Export a stack + +To export a stack and all its associated resources as a template, use the +`influx export stack` command. +Provide the following: + +- **Organization name** or **ID** +- **API token** with read access to the organization +- **Destination path and filename** for the template manifest. + The filename extension determines the template format—both **YAML** (`.yml`) and + **JSON** (`.json`) are supported. +- **Stack ID** + +###### Export a stack as a template + +```sh +# Syntax +influx export stack \ + -o \ + -t \ + -f \ + + +# Example +influx export stack \ + -o my-org \ + -t mYSuP3RS3CreTt0K3n + -f ~/templates/awesome-template.yml \ + 05dbb791a4324000 +``` + +## Include user-definable resource names + +After exporting a template manifest, replace resource names with **environment references** +to let users customize resource names when installing your template. + +1. [Export a template](#export-a-template) +2. Select any of the following resource fields to update: + + - `metadata.name` + - `associations[].name` + - `endpointName` _(unique to `NotificationRule` resources)_ + +3. Replace the resource field value with an `envRef` object with a `key` property + that references the key of a key-value pair the user provides when installing the template. + During installation, the `envRef` object is replaced by the value of the + referenced key-value pair. + If the user does not provide the environment reference key-value pair, InfluxDB + uses the `key` string as the default value. + + {{< code-tabs-wrapper >}} + {{% code-tabs %}} +[YAML](#) +[JSON](#) + {{% /code-tabs %}} + {{% code-tab-content %}} +```yml +apiVersion: influxdata.com/v2alpha1 +kind: Bucket +metadata: + name: + envRef: + key: bucket-name-1 +``` + {{% /code-tab-content %}} + {{% code-tab-content %}} +```json +{ + "apiVersion": "influxdata.com/v2alpha1", + "kind": "Bucket", + "metadata": { + "name": { + "envRef": { + "key": "bucket-name-1" + } + } + } +} +``` + {{% /code-tab-content %}} + {{< /code-tabs-wrapper >}} + +Using the example above, users are prompted to provide a value for `bucket-name-1` +when [applying the template](/influxdb/v2.1/influxdb-templates/use/#apply-templates). +Users can also include the `--env-ref` flag with the appropriate key-value pair +when installing the template. + +```sh +# Set bucket-name-1 to "myBucket" +influx apply \ + -f /path/to/template.yml \ + --env-ref=bucket-name-1=myBucket +``` + +_If sharing your template, we recommend documenting what environment references +exist in the template and what keys to use to replace them._ + +{{% note %}} +#### Resource fields that support environment references + +Only the following fields support environment references: + +- `metadata.name` +- `spec.endpointName` +- `spec.associations.name` +{{% /note %}} + +## Share your InfluxDB templates + +Share your InfluxDB templates with the entire InfluxData community. +**Contribute your template to the [InfluxDB Community Templates](https://github.com/influxdata/community-templates/) +repository on GitHub.** + +View InfluxDB Community Templates diff --git a/content/influxdb/v2.1/influxdb-templates/monitor.md b/content/influxdb/v2.1/influxdb-templates/monitor.md new file mode 100644 index 0000000000..e1fff69d19 --- /dev/null +++ b/content/influxdb/v2.1/influxdb-templates/monitor.md @@ -0,0 +1,181 @@ +--- +title: Monitor InfluxDB OSS using a template +description: > + Monitor your InfluxDB OSS instance using InfluxDB Cloud and + a pre-built InfluxDB template. +menu: + influxdb_2_1: + parent: Monitor with templates + name: Monitor InfluxDB OSS +weight: 102 +influxdb/v2.1/tags: [templates, monitor] +related: + - /influxdb/v2.1/reference/cli/influx/apply/ + - /influxdb/v2.1/reference/cli/influx/template/ +--- + +Use [InfluxDB Cloud](/influxdb/cloud/), the [InfluxDB Open Source (OSS) Metrics template](https://github.com/influxdata/community-templates/tree/master/influxdb2_oss_metrics), and Telegraf to monitor one or more InfluxDB OSS instances. + +Do the following: + +1. [Review requirements](#review-requirements) +2. [Install the InfluxDB OSS Monitoring template](#install-the-influxdb-oss-monitoring-template) +3. [Set up InfluxDB OSS for monitoring](#set-up-influxdb-oss-for-monitoring) +4. [Set up Telegraf](#set-up-telegraf) +5. [View the Monitoring dashboard](#view-the-monitoring-dashboard) +6. (Optional) [Alert when metrics stop reporting](#alert-when-metrics-stop-reporting) +7. (Optional) [Create a notification endpoint and rule](#create-a-notification-endpoint-and-rule) + +## Review requirements + +Before you begin, make sure you have access to the following: + + - InfluxDB Cloud account ([sign up for free here](https://cloud2.influxdata.com/signup)) + - Command line access to a machine [running InfluxDB OSS 2.x](/influxdb/v2.1/install/) and permissions to install Telegraf on this machine + - Internet connectivity from the machine running InfluxDB OSS 2.x and Telegraf to InfluxDB Cloud + - Sufficient resource availability to install the template. InfluxDB Cloud Free Plan accounts include [resource limits](/influxdb/cloud/account-management/pricing-plans/#resource-limits/influxdb/cloud/account-management/pricing-plans/#resource-limits) + +## Install the InfluxDB OSS Monitoring template + +The InfluxDB OSS Monitoring template includes a Telegraf configuration that sends InfluxDB OSS metrics to an InfluxDB endpoint and a dashboard that visualizes the metrics. + +1. [Log into your InfluxDB Cloud account](https://cloud2.influxdata.com/), go to **Settings > Templates**, and enter the following template URL: + + ``` + https://raw.githubusercontent.com/influxdata/community-templates/master/influxdb2_oss_metrics/influxdb2_oss_metrics.yml + ``` + +2. Click **Lookup Template**, and then click **Install Template**. InfluxDB Cloud imports the template, which includes the following resources: + - Dashboard `InfluxDB OSS Metrics` + - Telegraf configuration `scrape-influxdb-oss-telegraf` + - Bucket `oss_metrics` + - Check `InfluxDB OSS Deadman` + - Labels `influxdb2` and `prometheus` + +## Set up InfluxDB OSS for monitoring + +By default, InfluxDB OSS 2.x has a `/metrics` endpoint available, which exports Prometheus-style system metrics. + +1. Make sure the `/metrics` endpoint is [enabled](/{{< latest "influxdb" >}}/reference/config-options/#metrics-disabled). If you've changed the default settings to disable the `/metrics` endpoint, [re-enable these settings](/{{< latest "influxdb" >}}/reference/config-options/#metrics-disabled). +2. Navigate to the `/metrics` endpoint of your InfluxDB OSS instance to view the InfluxDB OSS system metrics in your browser: + + ``` + http://localhost:8086/metrics + ``` + + Or use `curl` to fetch metrics: + + ```sh + curl http://localhost:8086/metrics + # HELP boltdb_reads_total Total number of boltdb reads + # TYPE boltdb_reads_total counter + boltdb_reads_total 41 + # HELP boltdb_writes_total Total number of boltdb writes + # TYPE boltdb_writes_total counter + boltdb_writes_total 28 + # HELP go_gc_duration_seconds A summary of the pause duration of garbage collection cycles. + ... + ``` +3. Verify the [Telegraf](/{{< latest "telegraf" >}}/) agent has network access to the `/metrics` endpoint for each monitored InfluxDB OSS instance. + +4. Add your **InfluxDB Cloud** account information (URL and organization) to your Telegraf configuration by doing the following: + 1. Go to **Load Data > Telegraf** [in your InfluxDB Cloud account](https://cloud2.influxdata.com/), and click **InfluxDB Output Plugin**. + 2. Copy the URL, token, organization, and bucket, close the window, and then click **Scrape InfluxDB OSS Metrics**. + 3. Replace `URL`, `token', `organization`, and `bucket` under `outputs.influxdb_v2` with your InfluxDB Cloud account information. Alternatively, store this information in your environment variables and include the environment variables in your configuration. + + {{% note %}} +To ensure the InfluxDB OSS monitoring dashboard can display the recorded metrics, set the destination bucket name to `oss_metrics` in your `telegraf.conf`. + {{% /note %}} + + 4. Add the [Prometheus input plugin](https://github.com/influxdata/telegraf/blob/release-1.19/plugins/inputs/prometheus/README.md) to your `telegraf.conf`. Specify your your InfluxDB OSS URL(s) in the `urls` parameter. For example: + + {{< keep-url >}} + ```toml + [[inputs.prometheus]] + urls = ["http://localhost:8086/metrics"] + ``` + + If you're using unique URLs or have security set up for your `/metrics` endpoint, configure those options here and save the updated configuration. + + For more information about customizing Telegraf, see [Configure Telegraf](/{{< latest "telegraf" >}}/administration/configuration/#global-tags). +5. Click **Save Changes**. + +## Set up Telegraf + +Set up Telegraf to scrape metrics from InfluxDB OSS to send to your InfluxDB Cloud account. + +On each InfluxDB OSS instance you want to monitor, do the following: + +1. Go to **Load Data > Telegraf** [in your InfluxDB Cloud account](https://cloud2.influxdata.com/). +2. Click **Setup Instructions** under **Scrape InfluxDB OSS Metrics**. +3. Complete the Telegraf Setup instructions. + + {{% note %}} +For your API token, generate a new token or use an existing All Access token. If you run Telegraf as a service, edit your init script to set the environment variable and ensure its available to the service. + {{% /note %}} + +Telegraf runs quietly in the background (no immediate output appears), and Telegraf begins pushing metrics to your InfluxDB Cloud account. + +## View the Monitoring dashboard + +To see your data in real time, view the Monitoring dashboard. + +1. Select **Boards** (**Dashboards**) in your **InfluxDB Cloud** account. + + {{< nav-icon "dashboards" >}} + +2. Click **InfluxDB OSS Metrics**. Metrics appear in your dashboard. +3. Customize your monitoring dashboard as needed. For example, send an alert in the following cases: + - Users create a new task or bucket + - You're testing machine limits + - [Metrics stop reporting](#alert-when-metrics-stop-reporting) + +## Alert when metrics stop reporting + +The Monitoring template includes a [deadman check](/influxdb/cloud/monitor-alert/checks/create/#deadman-check) to verify metrics are reported at regular intervals. + +To alert when data stops flowing from InfluxDB OSS instances to your InfluxDB Cloud account, do the following: + +1. [Customize the deadman check](#customize-the-deadman-check) to identify the fields you want to monitor. +2. [Create a notification endpoint and rule](#create-a-notification-endpoint-and-rule) to receive notifications when your deadman check is triggered. + +### Customize the deadman check + +1. To view the deadman check, click **Alerts** in the navigation bar of your **InfluxDB Cloud** account. + + {{< nav-icon "alerts" >}} + + {{< img-hd src="/img/influxdb/2-0-monitor-oss-deadman.png" />}} +2. Choose a InfluxDB OSS field or create a new OSS field for your deadman alert: + 1. Click **{{< icon "plus" >}} Create** and select **Deadman Check** in the dropown menu. + 2. Define your query with at least one field. + 3. Click **Submit** and **Configure Check**. + When metrics stop reporting, you'll receive an alert. +3. Start under **Schedule Every**, set the amount of time to check for data. +4. Set the amount of time to wait before switching to a critical alert. +5. Save the Check and click on **View History** of the Check under the gear icon to verify it is running. + +## Create a notification endpoint and rule + +To receive a notification message when your deadman check is triggered, create a [notification endpoint](#create-a-notification-endpoint) and [rule](#create-a-notification-rule). + +### Create a notification endpoint + +InfluxData supports different endpoints: Slack, PagerDuty, and HTTP. Slack is free for all users, while PagerDuty and HTTP are exclusive to the Usage-Based Plan. + +#### Send a notification to Slack + +1. Create a [Slack Webhooks](https://api.slack.com/messaging/webhooks). +2. Go to **Alerts > Notification Endpoint** and click **{{< icon "plus" >}} Create**, and enter a name and description for your Slack endpoint. +3. Enter your Slack Webhook under **Incoming Webhook URL** and click **Create Notification Endpoint**. + +#### Send a notification to PagerDuty or HTTP + +Send a notification to PagerDuty or HTTP endpoints (other webhooks) by [upgrading your InfluxDB Cloud account](/influxdb/cloud/account-management/billing/#upgrade-to-usage-based-plan). + +### Create a notification rule + +[Create a notification rule](/influxdb/cloud/monitor-alert/notification-rules/create/) to set rules for when to send a deadman alert message to your notification endpoint. + +1. Go to **Alerts > Notification Rules** and click **{{< icon "plus" >}} Create**. +2. Fill out the **About** and **Conditions** section then click **Create Notification Rule**. diff --git a/content/influxdb/v2.1/influxdb-templates/stacks/_index.md b/content/influxdb/v2.1/influxdb-templates/stacks/_index.md new file mode 100644 index 0000000000..55fc29150d --- /dev/null +++ b/content/influxdb/v2.1/influxdb-templates/stacks/_index.md @@ -0,0 +1,26 @@ +--- +title: InfluxDB stacks +description: > + Use an InfluxDB stack to manage your InfluxDB templates—add, update, or remove templates over time. +menu: + influxdb_2_1: + parent: InfluxDB templates +weight: 105 +related: + - /influxdb/v2.1/reference/cli/influx/pkg/stack/ +--- + +Use InfluxDB stacks to manage [InfluxDB templates](/influxdb/v2.1/influxdb-templates). +When you apply a template, InfluxDB associates resources in the template with a stack. Use the stack to add, update, or remove InfluxDB templates over time. + + {{< children type="anchored-list" >}} + + {{< children readmore=true >}} + +{{% note %}} +**Key differences between stacks and templates**: + +- A template defines a set of resources in a text file outside of InfluxDB. When you apply a template, a stack is automatically created to manage the applied template. +- Stacks add, modify or delete resources in an instance. +- Templates do not recognize resources in an instance. All resources in the template are added, creating duplicate resources if a resource already exists. + {{% /note %}} diff --git a/content/influxdb/v2.1/influxdb-templates/stacks/init.md b/content/influxdb/v2.1/influxdb-templates/stacks/init.md new file mode 100644 index 0000000000..fc4d867987 --- /dev/null +++ b/content/influxdb/v2.1/influxdb-templates/stacks/init.md @@ -0,0 +1,73 @@ +--- +title: Initialize an InfluxDB stack +list_title: Initialize a stack +description: > + InfluxDB automatically creates a new stack each time you [apply an InfluxDB template](/influxdb/v2.1/influxdb-templates/use/) + **without providing a stack ID**. + To manually create or initialize a new stack, use the [`influx stacks init` command](/influxdb/v2.1/reference/cli/influx/stacks/init/). +menu: + influxdb_2_1: + parent: InfluxDB stacks + name: Initialize a stack +weight: 202 +related: + - /influxdb/v2.1/reference/cli/influx/stacks/init/ +list_code_example: | + ```sh + influx apply \ + -o example-org \ + -f path/to/template.yml + ``` + ```sh + influx stacks init \ + -o example-org \ + -n "Example Stack" \ + -d "InfluxDB stack for monitoring some awesome stuff" \ + -u https://example.com/template-1.yml \ + -u https://example.com/template-2.yml + ``` +--- + +InfluxDB automatically creates a new stack each time you [apply an InfluxDB template](/influxdb/v2.1/influxdb-templates/use/) +**without providing a stack ID**. +To manually create or initialize a new stack, use the [`influx stacks init` command](/influxdb/v2.1/reference/cli/influx/stacks/init/). + +## Initialize a stack when applying a template +To automatically create a new stack when [applying an InfluxDB template](/influxdb/v2.1/influxdb-templates/use/) +**don't provide a stack ID**. +InfluxDB applies the resources in the template to a new stack and provides the **stack ID** the output. + +```sh +influx apply \ + -o example-org \ + -f path/to/template.yml +``` + +## Manually initialize a new stack +Use the [`influx stacks init` command](/influxdb/v2.1/reference/cli/influx/stacks/init/) +to create or initialize a new InfluxDB stack. + +**Provide the following:** + +- Organization name or ID +- Stack name +- Stack description +- InfluxDB template URLs + + +```sh +# Syntax +influx stacks init \ + -o \ + -n \ + -d + +# Example +influx stacks init \ + -o example-org \ + -n "Example Stack" \ + -d "InfluxDB stack for monitoring some awesome stuff" \ + -u https://example.com/template-1.yml \ + -u https://example.com/template-2.yml +``` diff --git a/content/influxdb/v2.1/influxdb-templates/stacks/remove.md b/content/influxdb/v2.1/influxdb-templates/stacks/remove.md new file mode 100644 index 0000000000..c89f9b262e --- /dev/null +++ b/content/influxdb/v2.1/influxdb-templates/stacks/remove.md @@ -0,0 +1,39 @@ +--- +title: Remove an InfluxDB stack +list_title: Remove a stack +description: > + Use the [`influx stacks remove` command](/influxdb/v2.1/reference/cli/influx/stacks/remove/) + to remove an InfluxDB stack and all its associated resources. +menu: + influxdb_2_1: + parent: InfluxDB stacks + name: Remove a stack +weight: 205 +related: + - /influxdb/v2.1/reference/cli/influx/stacks/remove/ +list_code_example: | + ```sh + influx stacks remove \ + -o example-org \ + --stack-id=12ab34cd56ef + ``` +--- + +Use the [`influx stacks remove` command](/influxdb/v2.1/reference/cli/influx/stacks/remove/) +to remove an InfluxDB stack and all its associated resources. + +**Provide the following:** + +- Organization name or ID +- Stack ID + + +```sh +# Syntax +influx stacks remove -o --stack-id= + +# Example +influx stacks remove \ + -o example-org \ + --stack-id=12ab34cd56ef +``` diff --git a/content/influxdb/v2.1/influxdb-templates/stacks/save-time.md b/content/influxdb/v2.1/influxdb-templates/stacks/save-time.md new file mode 100644 index 0000000000..07e90ba92b --- /dev/null +++ b/content/influxdb/v2.1/influxdb-templates/stacks/save-time.md @@ -0,0 +1,165 @@ +--- +title: Save time with InfluxDB stacks +list_title: Save time with stacks +description: > + Discover how to use InfluxDB stacks to save time. +menu: + influxdb_2_1: + parent: InfluxDB stacks + name: Save time with stacks +weight: 201 +related: + - /influxdb/v2.1/reference/cli/influx/stacks/ + +--- + +Save time and money using InfluxDB stacks. Here's a few ideal use cases: + +- [Automate deployments with GitOps and stacks](#automate-deployments-with-gitops-and-stacks) +- [Apply updates from source-controlled templates](#apply-updates-from-source-controlled-templates) +- [Apply template updates across multiple InfluxDB instances](#apply-template-updates-across-multiple-influxdb-instances) +- [Develop templates](#develop-templates) + +### Automate deployments with GitOps and stacks + +GitOps is popular way to configure and automate deployments. Use InfluxDB stacks in a GitOps workflow +to automatically update distributed instances of InfluxDB OSS or InfluxDB Cloud. + +To automate an InfluxDB deployment with GitOps and stacks, complete the following steps: + +1. [Set up a GitHub repository](#set-up-a-github-repository) +2. [Add existing resources to the GitHub repository](#add-existing-resources-to-the-github-repository) +3. [Automate the creation of a stack for each folder](#automate-the-creation-of-a-stack-for-each-folder) +4. [Set up Github Actions or CircleCI](#set-up-github-actions-or-circleci) + +#### Set up a GitHub repository + +Set up a GitHub repository to back your InfluxDB instance. Determine how you want to organize the resources in your stacks within your Github repository. For example, organize resources under folders for specific teams or functions. + +We recommend storing all resources for one stack in the same folder. For example, if you monitor Redis, create a `redis` stack and put your Redis monitoring resources (a Telegraf configuration, four dashboards, a label, and two alert checks) into one Redis folder, each resource in a separate file. Then, when you need to update a Redis resource, it's easy to find and make changes in one location. + + {{% note %}} + Typically, we **do not recommend** using the same resource in multiple stacks. If your organization uses the same resource in multiple stacks, before you delete a stack, verify the stack does not include resources that another stack depends on. Stacks with buckets often contain data used by many different templates. Because of this, we recommend keeping buckets separate from the other stacks. + {{% /note %}} + +#### Add existing resources to the GitHub repository + +Skip this section if you are starting from scratch or don’t have existing resources you want to add to your stack. + +Use the `influx export` command to quickly export resources. Keep all your resources in a single file or have files for each one. You can always split or combine them later. + +For example, if you export resources for three stacks: `buckets`, `redis`, and `mysql`, your folder structure might look something like this when you are done: + + ```sh + influxdb-assets/ + ├── buckets/ + │ ├── telegraf_bucket.yml + ├── redis/ + │ ├── redis_overview_dashboard.yml + │ ├── redis_label.yml + │ ├── redis_cpu_check.yml + │ └── redis_mem_check.yml + ├── mysql/ + │ ├── mysql_assets.yml + └── README.md + + ``` + {{% note %}} + When you export a resource, InfluxDB creates a `meta.name` for that resource. These resource names should be unique inside your InfluxDB instance. Use a good naming convention to prevent duplicate `meta.names`. Changing the `meta.name` of the InfluxDB resource will cause the stack to orphan the resource with the previous name and create a new resource with the updated name. + {{% /note %}} + +Add the exported resources to your new GitHub repository. + +#### Automate the creation of a stack for each folder + +To automatically create a stack from each folder in your GitHub repository, create a shell script to check for an existing stack and if the stack isn't found, use the `influx stacks init` command to create a new stack. The following sample script creates a `redis` stack and automatically applies those changes to your instance: + +```sh +echo "Checking for existing redis stack..." +REDIS_STACK_ID=$(influx stacks --stack-name redis --json | jq -r '.[0].ID') +if [ "$REDIS_STACK_ID" == "null" ]; then + echo "No stack found. Initializing our stack..." + REDIS_STACK_ID=$(influx stacks init -n redis --json | jq -r '.ID') +fi + +# Setting the base path +BASE_PATH="$(pwd)" + +echo "Applying our redis stack..." +cat $BASE_PATH/redis/*.yml | \ +influx apply --force true --stack-id $REDIS_STACK_ID -q +``` + + {{% note %}} + The `--json` flag in the InfluxDB CLI is very useful when scripting against the CLI. This flag lets you grab important information easily using [`jq`](https://stedolan.github.io/jq/manual/v1.6/). + {{% /note %}} + +Repeat this step for each of the stacks in your repository. When a resource in your stack changes, re-run this script to apply updated resources to your InfluxDB instance. Re-applying a stack with an updated resource won't add, delete, or duplicate resources. + +#### Set up Github Actions or CircleCI + +Once you have a script to apply changes being made to your local instance, automate the deployment to other environments as needed. Use the InfluxDB CLI to maintain multiple [configuration profiles]() to easily switch profile and issue commands against other InfluxDB instances. To apply the same script to a different InfluxDB instance, change your active configuration profile using the `influx config set` command. Or set the desired profile dynamically using the `-c, --active-config` flag. + + {{% note %}} + Before you run automation scripts against shared environments, we recommend manually running the steps in your script. + {{% /note %}} + +Verify your deployment automation software lets you run a custom script, and then set up the custom script you've built locally another environment. For example, here's a custom Github Action that automates deployment: + +```yml +name: deploy-influxdb-resources + +on: + push: + branches: [ master ] + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + with: + ref: ${{ github.ref }} + - name: Deploys repo to cloud + env: + # These secrets can be configured in the Github repo to connect to + # your InfluxDB instance. + INFLUX_TOKEN: ${{ secrets.INFLUX_TOKEN }} + INFLUX_ORG: ${{ secrets.INFLUX_ORG }} + INFLUX_URL: ${{ secrets.INFLUX_URL }} + GITHUB_REPO: ${{ github.repository }} + GITHUB_BRANCH: ${{ github.ref }} + run: | + cd /tmp + wget https://dl.influxdata.com/platform/nightlies/influx_nightly_linux_amd64.tar.gz + tar xvfz influx_nightly_linux_amd64.tar.gz + sudo cp influx_nightly_linux_amd64/influx /usr/local/bin/ + cd $GITHUB_WORKSPACE + # This runs the script to set up your stacks + chmod +x ./setup.sh + ./setup.sh prod +``` + +For more information about using GitHub Actions in your project, check out the complete [Github Actions documentation](https://github.com/features/actions). + +### Apply updates from source-controlled templates + +You can use a variety of InfluxDB templates from many different sources including +[Community Templates](https://github.com/influxdata/community-templates/) or +self-built custom templates. +As templates are updated over time, stacks let you gracefully +apply updates without creating duplicate resources. + +### Apply template updates across multiple InfluxDB instances + +In many cases, you may have more than one instance of InfluxDB running and want to apply +the same template to each separate instance. +Using stacks, you can make changes to a stack on one instance, +[export the stack as a template](/influxdb/v2.1/influxdb-templates/create/#export-a-stack) +and then apply the changes to your other InfluxDB instances. + +### Develop templates + +InfluxDB stacks aid in developing and maintaining InfluxDB templates. +Stacks let you modify and update template manifests and apply those changes in +any stack that uses the template. diff --git a/content/influxdb/v2.1/influxdb-templates/stacks/update.md b/content/influxdb/v2.1/influxdb-templates/stacks/update.md new file mode 100644 index 0000000000..a637594bbb --- /dev/null +++ b/content/influxdb/v2.1/influxdb-templates/stacks/update.md @@ -0,0 +1,56 @@ +--- +title: Update an InfluxDB stack +list_title: Update a stack +description: > + Use the [`influx apply` command](/influxdb/v2.1/reference/cli/influx/apply/) + to update a stack with a modified template. + When applying a template to an existing stack, InfluxDB checks to see if the + resources in the template match existing resources. + InfluxDB updates, adds, and removes resources to resolve differences between + the current state of the stack and the newly applied template. +menu: + influxdb_2_1: + parent: InfluxDB stacks + name: Update a stack +weight: 203 +related: + - /influxdb/v2.1/reference/cli/influx/apply + - /influxdb/v2.1/reference/cli/influx/stacks/update/ +list_code_example: | + ```sh + influx apply \ + -o example-org \ + -u http://example.com/template-1.yml \ + -u http://example.com/template-2.yml \ + --stack-id=12ab34cd56ef + ``` +--- + +Use the [`influx apply` command](/influxdb/v2.1/reference/cli/influx/apply/) +to update a stack with a modified template. +When applying a template to an existing stack, InfluxDB checks to see if the +resources in the template match existing resources. +InfluxDB updates, adds, and removes resources to resolve differences between +the current state of the stack and the newly applied template. + +Each stack is uniquely identified by a **stack ID**. +For information about retrieving your stack ID, see [View stacks](/influxdb/v2.1/influxdb-templates/stacks/view/). + +**Provide the following:** + +- Organization name or ID +- Stack ID +- InfluxDB template URLs to apply + + +```sh +influx apply \ + -o example-org \ + -u http://example.com/template-1.yml \ + -u http://example.com/template-2.yml \ + --stack-id=12ab34cd56ef +``` + +Template resources are uniquely identified by their `metadata.name` field. +If errors occur when applying changes to a stack, all applied changes are +reversed and the stack is returned to its previous state. diff --git a/content/influxdb/v2.1/influxdb-templates/stacks/view.md b/content/influxdb/v2.1/influxdb-templates/stacks/view.md new file mode 100644 index 0000000000..25b1c8ec9a --- /dev/null +++ b/content/influxdb/v2.1/influxdb-templates/stacks/view.md @@ -0,0 +1,69 @@ +--- +title: View InfluxDB stacks +list_title: View stacks +description: > + Use the [`influx stacks` command](/influxdb/v2.1/reference/cli/influx/stacks/) + to view installed InfluxDB stacks and their associated resources. +menu: + influxdb_2_1: + parent: InfluxDB stacks + name: View stacks +weight: 204 +related: + - /influxdb/v2.1/reference/cli/influx/stacks/ +list_code_example: | + ```sh + influx stacks -o example-org + ``` +--- + +Use the [`influx stacks` command](/influxdb/v2.1/reference/cli/influx/stacks/) +to view installed InfluxDB stacks and their associated resources. + +**Provide the following:** + +- Organization name or ID + + +```sh +# Syntax +influx stacks -o + +# Example +influx stacks -o example-org +``` + +### Filter stacks + +To output information about specific stacks, use the `--stack-name` or `--stack-id` +flags to filter output by stack names or stack IDs. + +##### Filter by stack name + +```sh +# Syntax +influx stacks \ + -o \ + --stack-name= + +# Example +influx stacks \ + -o example-org \ + --stack-name=stack1 \ + --stack-name=stack2 +``` + +### Filter by stack ID + +```sh +# Syntax +influx stacks \ + -o \ + --stack-id= + +# Example +influx stacks \ + -o example-org \ + --stack-id=12ab34cd56ef \ + --stack-id=78gh910i11jk +``` diff --git a/content/influxdb/v2.1/influxdb-templates/use.md b/content/influxdb/v2.1/influxdb-templates/use.md new file mode 100644 index 0000000000..fc48a17333 --- /dev/null +++ b/content/influxdb/v2.1/influxdb-templates/use.md @@ -0,0 +1,241 @@ +--- +title: Use InfluxDB templates +description: > + Use the `influx` command line interface (CLI) to summarize, validate, and apply + templates from your local filesystem and from URLs. +menu: + influxdb_2_1: + parent: InfluxDB templates + name: Use templates +weight: 102 +influxdb/v2.1/tags: [templates] +related: + - /influxdb/v2.1/reference/cli/influx/apply/ + - /influxdb/v2.1/reference/cli/influx/template/ + - /influxdb/v2.1/reference/cli/influx/template/validate/ +--- + +Use the `influx` command line interface (CLI) to summarize, validate, and apply +templates from your local filesystem and from URLs. + +- [Use InfluxDB community templates](#use-influxdb-community-templates) +- [View a template summary](#view-a-template-summary) +- [Validate a template](#validate-a-template) +- [Apply templates](#apply-templates) + + +## Use InfluxDB community templates +The [InfluxDB community templates repository](https://github.com/influxdata/community-templates/) +is home to a growing number of InfluxDB templates developed and maintained by +others in the InfluxData community. +Apply community templates directly from GitHub using a template's download URL +or download the template. + +{{< youtube 2JjW4Rym9XE >}} + +{{% note %}} +When attempting to access the community templates via the URL, the templates use the following +as the root of the URL: + +```sh +https://raw.githubusercontent.com/influxdata/community-templates/master/ +``` + +For example, the Docker community template can be accessed via: + +```sh +https://raw.githubusercontent.com/influxdata/community-templates/master/docker/docker.yml +``` +{{% /note %}} + +View InfluxDB Community Templates + +## View a template summary +To view a summary of what's included in a template before applying the template, +use the [`influx template` command](/influxdb/v2.1/reference/cli/influx/template/). +View a summary of a template stored in your local filesystem or from a URL. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[From a file](#) +[From a URL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +# Syntax +influx template -f + +# Example +influx template -f /path/to/template.yml +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sh +# Syntax +influx template -u + +# Example +influx template -u https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +## Validate a template +To validate a template before you install it or troubleshoot a template, use +the [`influx template validate` command](/influxdb/v2.1/reference/cli/influx/template/validate/). +Validate a template stored in your local filesystem or from a URL. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[From a file](#) +[From a URL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +# Syntax +influx template validate -f + +# Example +influx template validate -f /path/to/template.yml +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sh +# Syntax +influx template validate -u + +# Example +influx template validate -u https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +## Apply templates +Use the [`influx apply` command](/influxdb/v2.1/reference/cli/influx/apply/) to install templates +from your local filesystem or from URLs. + +- [Apply a template from a file](#apply-a-template-from-a-file) +- [Apply all templates in a directory](#apply-all-templates-in-a-directory) +- [Apply a template from a URL](#apply-a-template-from-a-url) +- [Apply templates from both files and URLs](#apply-templates-from-both-files-and-urls) +- [Define environment references](#define-environment-references) +- [Include a secret when installing a template](#include-a-secret-when-installing-a-template) + +{{% note %}} +#### Apply templates to an existing stack +To apply a template to an existing stack, include the stack ID when applying the template. +Any time you apply a template without a stack ID, InfluxDB initializes a new stack +and all new resources. +For more information, see [InfluxDB stacks](/influxdb/v2.1/influxdb-templates/stacks/). +{{% /note %}} + +### Apply a template from a file +To install templates stored on your local machine, use the `-f` or `--file` flag +to provide the **file path** of the template manifest. + +```sh +# Syntax +influx apply -o -f + +# Examples +# Apply a single template +influx apply -o example-org -f /path/to/template.yml + +# Apply multiple templates +influx apply -o example-org \ + -f /path/to/this/template.yml \ + -f /path/to/that/template.yml +``` + +### Apply all templates in a directory +To apply all templates in a directory, use the `-f` or `--file` flag to provide +the **directory path** of the directory where template manifests are stored. +By default, this only applies templates stored in the specified directory. +To apply all templates stored in the specified directory and its subdirectories, +include the `-R`, `--recurse` flag. + +```sh +# Syntax +influx apply -o -f + +# Examples +# Apply all templates in a directory +influx apply -o example-org -f /path/to/template/dir/ + +# Apply all templates in a directory and its subdirectories +influx apply -o example-org -f /path/to/template/dir/ -R +``` + +### Apply a template from a URL +To apply templates from a URL, use the `-u` or `--template-url` flag to provide the URL +of the template manifest. + +```sh +# Syntax +influx apply -o -u + +# Examples +# Apply a single template from a URL +influx apply -o example-org -u https://example.com/templates/template.yml + +# Apply multiple templates from URLs +influx apply -o example-org \ + -u https://example.com/templates/template1.yml \ + -u https://example.com/templates/template2.yml +``` + +### Apply templates from both files and URLs +To apply templates from both files and URLs in a single command, include multiple +file or directory paths and URLs, each with the appropriate `-f` or `-u` flag. + +```sh +# Syntax +influx apply -o -u -f + +# Example +influx apply -o example-org \ + -u https://example.com/templates/template1.yml \ + -u https://example.com/templates/template2.yml \ + -f ~/templates/custom-template.yml \ + -f ~/templates/iot/home/ \ + --recurse +``` + +### Define environment references +Some templates include [environment references](/influxdb/v2.1/influxdb-templates/create/#include-user-definable-resource-names) that let you provide custom resource names. +The `influx apply` command prompts you to provide a value for each environment +reference in the template. +You can also provide values for environment references by including an `--env-ref` +flag with a key-value pair comprised of the environment reference key and the +value to replace it. + +```sh +influx apply -o example-org -f /path/to/template.yml \ + --env-ref=bucket-name-1=myBucket + --env-ref=label-name-1=Label1 \ + --env-ref=label-name-2=Label2 +``` + +### Include a secret when installing a template +Some templates use [secrets](/influxdb/v2.1/security/secrets/) in queries. +Secret values are not included in templates. +To define secret values when installing a template, include the `--secret` flag +with the secret key-value pair. + +```sh +# Syntax +influx apply -o -f \ + --secret== + +# Examples +# Define a single secret when applying a template +influx apply -o example-org -f /path/to/template.yml \ + --secret=FOO=BAR + +# Define multiple secrets when applying a template +influx apply -o example-org -f /path/to/template.yml \ + --secret=FOO=bar \ + --secret=BAZ=quz +``` + +_To add a secret after applying a template, see [Add secrets](/influxdb/v2.1/security/secrets/manage-secrets/add/)._ diff --git a/content/influxdb/v2.1/install.md b/content/influxdb/v2.1/install.md new file mode 100644 index 0000000000..fd3f8cde9d --- /dev/null +++ b/content/influxdb/v2.1/install.md @@ -0,0 +1,752 @@ +--- +title: Install InfluxDB +description: Download, install, and set up InfluxDB OSS. +menu: influxdb_2_1 +weight: 2 +influxdb/v2.1/tags: [install] +--- + +The InfluxDB {{< current-version >}} time series platform is purpose-built to collect, store, +process and visualize metrics and events. +Download, install, and set up InfluxDB OSS. + +{{< tabs-wrapper >}} +{{% tabs %}} +[macOS](#) +[Linux](#) +[Windows](#) +[Docker](#) +[Kubernetes](#) +[Raspberry Pi](#) +{{% /tabs %}} + + +{{% tab-content %}} +## Install InfluxDB v{{< current-version >}} + +Do one of the following: + +- [Use Homebrew](#use-homebrew) +- [Manually download and install](#manually-download-and-install) + +{{% note %}} +#### InfluxDB and the influx CLI are separate packages +The InfluxDB server ([`influxd`](/influxdb/v2.1/reference/cli/influxd/)) and the +[`influx` CLI](/influxdb/v2.1/reference/cli/influx/) are packaged and +versioned separately. +For information about installing the `influx` CLI, see +[Install and use the influx CLI](/influxdb/v2.1/tools/influx-cli/). +{{% /note %}} + +### Use Homebrew + +We recommend using [Homebrew](https://brew.sh/) to install InfluxDB v{{< current-version >}} on macOS: + +```sh +brew update +brew install influxdb +``` + +{{% note %}} +Homebrew also installs `influx-cli` as a dependency. +For information about using the `influx` CLI, see the +[`influx` CLI reference documentation](/influxdb/v2.1/reference/cli/influx/). +{{% /note %}} + +### Manually download and install + +To download the InfluxDB v{{< current-version >}} binaries for macOS directly, +do the following: + +1. **Download the InfluxDB package.** + + InfluxDB v{{< current-version >}} (macOS) + + +2. **Unpackage the InfluxDB binary.** + + Do one of the following: + + - Double-click the downloaded package file in **Finder**. + - Run the following command in a macOS command prompt application such + **Terminal** or **[iTerm2](https://www.iterm2.com/)**: + + ```sh + # Unpackage contents to the current working directory + tar zxvf ~/Downloads/influxdb2-{{< latest-patch >}}-darwin-amd64.tar.gz + ``` + +3. **(Optional) Place the binary in your `$PATH`** + + ```sh + # (Optional) Copy the influxd binary to your $PATH + sudo cp influxdb2-{{< latest-patch >}}-darwin-amd64/influxd /usr/local/bin/ + ``` + + If you do not move the `influxd` binary into your `$PATH`, prefix the executable + `./` to run it in place. + +{{< expand-wrapper >}} +{{% expand "Recommended – Verify the authenticity of downloaded binary" %}} + +For added security, use `gpg` to verify the signature of your download. +(Most operating systems include the `gpg` command by default. +If `gpg` is not available, see the [GnuPG homepage](https://gnupg.org/download/) for installation instructions.) + +1. Download and import InfluxData's public key: + + ``` + curl -s https://repos.influxdata.com/influxdb2.key | gpg --import - + ``` + +2. Download the signature file for the release by adding `.asc` to the download URL. +For example: + + ``` + wget https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-darwin-amd64.tar.gz.asc + ``` + +3. Verify the signature with `gpg --verify`: + + ``` + gpg --verify influxdb2-{{< latest-patch >}}-darwin-amd64.tar.gz.asc influxdb2-{{< latest-patch >}}-darwin-amd64.tar.gz + ``` + + The output from this command should include the following: + + ``` + gpg: Good signature from "InfluxData " [unknown] + ``` +{{% /expand %}} +{{< /expand-wrapper >}} + +{{% note %}} +Both InfluxDB 1.x and 2.x have associated `influxd` and `influx` binaries. +If InfluxDB 1.x binaries are already in your `$PATH`, run the {{< current-version >}} binaries in place +or rename them before putting them in your `$PATH`. +If you rename the binaries, all references to `influxd` and `influx` in this documentation refer to your renamed binaries. +{{% /note %}} + +#### Networking ports + +By default, InfluxDB uses TCP port `8086` for client-server communication over +the [InfluxDB HTTP API](/influxdb/v2.1/reference/api/). + +### Start InfluxDB + +Start InfluxDB by running the `influxd` daemon: + +```bash +influxd +``` + +{{% note %}} +#### Run InfluxDB on macOS Catalina + +macOS Catalina requires downloaded binaries to be signed by registered Apple developers. +Currently, when you first attempt to run `influxd`, macOS will prevent it from running. +To manually authorize the `influxd` binary: + +1. Attempt to run `influxd`. +2. Open **System Preferences** and click **Security & Privacy**. +3. Under the **General** tab, there is a message about `influxd` being blocked. + Click **Open Anyway**. + +We are in the process of updating our build process to ensure released binaries are signed by InfluxData. +{{% /note %}} + +{{% warn %}} +#### "too many open files" errors + +After running `influxd`, you might see an error in the log output like the +following: + +```sh +too many open files +``` + +To resolve this error, follow the +[recommended steps](https://unix.stackexchange.com/a/221988/471569) to increase +file and process limits for your operating system version then restart `influxd`. + +{{% /warn %}} + +_See the [`influxd` documentation](/influxdb/v2.1/reference/cli/influxd) for information about +available flags and options._ + +{{% note %}} +#### InfluxDB "phone home" + +By default, InfluxDB sends telemetry data back to InfluxData. +The [InfluxData telemetry](https://www.influxdata.com/telemetry) page provides +information about what data is collected and how it is used. + +To opt-out of sending telemetry data back to InfluxData, include the +`--reporting-disabled` flag when starting `influxd`. + +```bash +influxd --reporting-disabled +``` +{{% /note %}} + +{{% /tab-content %}} + + + +{{% tab-content %}} +## Download and install InfluxDB v{{< current-version >}} + +{{% note %}} +#### InfluxDB and the influx CLI are separate packages +The InfluxDB server ([`influxd`](/influxdb/v2.1/reference/cli/influxd/)) and the +[`influx` CLI](/influxdb/v2.1/reference/cli/influx/) are packaged and +versioned separately. +For information about installing the `influx` CLI, see +[Install and use the influx CLI](/influxdb/v2.1/tools/influx-cli/). +{{% /note %}} + +1. **Download the InfluxDB package.** + + Download the InfluxDB package [from your browser](#download-from-your-browser) + or [from the command line](#download-from-the-command-line). + + #### Download from your browser + + InfluxDB v{{< current-version >}} (amd64) + InfluxDB v{{< current-version >}} (arm) + + #### Download from the command line + + ```sh + # amd64 + wget https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-linux-amd64.tar.gz + + # arm + wget https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-linux-arm64.tar.gz + ``` + +4. **Unpackage the downloaded package.** + + _**Note:** The following commands are examples. Adjust the filenames, paths, and utilities if necessary._ + + ```sh + # amd64 + tar xvzf path/to/influxdb2-{{< latest-patch >}}-linux-amd64.tar.gz + + # arm + tar xvzf path/to/influxdb2-{{< latest-patch >}}-linux-arm64.tar.gz + ``` + +3. **(Optional) Place the unpackaged `influxd` executable in your system `$PATH`.** + + ```sh + # amd64 + sudo cp influxdb2-{{< latest-patch >}}-linux-amd64/influxd /usr/local/bin/ + + # arm + sudo cp influxdb2-{{< latest-patch >}}-linux-amd64/influxd /usr/local/bin/ + ``` + + If you do not move the `influxd` binary into your `$PATH`, prefix the executable + `./` to run it in place. + +{{< expand-wrapper >}} +{{% expand "Recommended – Verify the authenticity of downloaded binary" %}} + +For added security, use `gpg` to verify the signature of your download. +(Most operating systems include the `gpg` command by default. +If `gpg` is not available, see the [GnuPG homepage](https://gnupg.org/download/) for installation instructions.) + +1. Download and import InfluxData's public key: + + ``` + curl -s https://repos.influxdata.com/influxdb2.key | gpg --import - + ``` + +2. Download the signature file for the release by adding `.asc` to the download URL. + For example: + + ``` + wget https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-linux-amd64.tar.gz.asc + ``` + +3. Verify the signature with `gpg --verify`: + + ``` + gpg --verify influxdb2-{{< latest-patch >}}-linux-amd64.tar.gz.asc influxdb2-{{< latest-patch >}}-linux-amd64.tar.gz + ``` + + The output from this command should include the following: + + ``` + gpg: Good signature from "InfluxData " [unknown] + ``` +{{% /expand %}} +{{< /expand-wrapper >}} + +## Start InfluxDB + +Start InfluxDB by running the `influxd` daemon: + +```bash +influxd +``` + +_See the [`influxd` documentation](/influxdb/v2.1/reference/cli/influxd) for information about +available flags and options._ + +## Install InfluxDB as a service with systemd + +1. Download and install the appropriate `.deb` or `.rpm` file using a URL from the + [InfluxData downloads page](https://portal.influxdata.com/downloads/) + with the following commands: + + ```sh + # Ubuntu/Debian + wget https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-xxx.deb + sudo dpkg -i influxdb2-{{< latest-patch >}}-xxx.deb + + # Red Hat/CentOS/Fedora + wget https://dl.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-xxx.rpm + sudo yum localinstall influxdb2-{{< latest-patch >}}-xxx.rpm + ``` + _Use the exact filename of the download of `.rpm` package (for example, `influxdb2-{{< latest-patch >}}-amd64.rpm`)._ + +2. Start the InfluxDB service: + + ```sh + sudo service influxdb start + ``` + + Installing the InfluxDB package creates a service file at `/lib/systemd/services/influxdb.service` + to start InfluxDB as a background service on startup. + +3. Restart your system and verify that the service is running correctly: + + ``` + $ sudo service influxdb status + ● influxdb.service - InfluxDB is an open-source, distributed, time series database + Loaded: loaded (/lib/systemd/system/influxdb.service; enabled; vendor preset: enable> + Active: active (running) + ``` + +When installed as a service, InfluxDB stores data in the following locations: + +- **Time series data:** `/var/lib/influxdb/engine/` +- **Key-value data:** `/var/lib/influxdb/influxd.bolt`. +- **influx CLI configurations:** `~/.influxdbv2/configs` _(see [`influx config`](/influxdb/v2.1/reference/cli/influx/config/) for more information)_ . + +To customize your InfluxDB configuration, use either +[command line flags (arguments)](#pass-arguments-to-systemd), environment variables, or an InfluxDB configuration file. +See InfluxDB [configuration options](/influxdb/v2.1/reference/config-options/) for more information. + +### Pass arguments to systemd + +1. Add one or more lines like the following containing arguments for `influxd` to `/etc/default/influxdb2`: + + ```sh + ARG1="--http-bind-address :8087" + ARG2="" + ``` + +2. Edit the `/lib/systemd/system/influxdb.service` file as follows: + + ```sh + ExecStart=/usr/bin/influxd $ARG1 $ARG2 + ``` + +### Networking ports + +By default, InfluxDB uses TCP port `8086` for client-server communication over +the [InfluxDB HTTP API](/influxdb/v2.1/reference/api/). + +{{% note %}} +#### InfluxDB "phone home" + +By default, InfluxDB sends telemetry data back to InfluxData. +The [InfluxData telemetry](https://www.influxdata.com/telemetry) page provides +information about what data is collected and how it is used. + +To opt-out of sending telemetry data back to InfluxData, include the +`--reporting-disabled` flag when starting `influxd`. + +```bash +influxd --reporting-disabled +``` +{{% /note %}} + +{{% /tab-content %}} + + + +{{% tab-content %}} +{{% note %}} +#### System requirements +- Windows 10 +- 64-bit AMD architecture +- [Powershell](https://docs.microsoft.com/powershell/) or + [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/) + +#### Command line examples +Use **Powershell** or **WSL** to execute `influx` and `influxd` commands. +The command line examples in this documentation use `influx` and `influxd` as if +installed on the system `PATH`. +If these binaries are not installed on your `PATH`, replace `influx` and `influxd` +in the provided examples with `./influx` and `./influxd` respectively. +{{% /note %}} + +## Download and install InfluxDB v{{< current-version >}} + +{{% note %}} +#### InfluxDB and the influx CLI are separate packages +The InfluxDB server ([`influxd`](/influxdb/v2.1/reference/cli/influxd/)) and the +[`influx` CLI](/influxdb/v2.1/reference/cli/influx/) are packaged and +versioned separately. +For information about installing the `influx` CLI, see +[Install and use the influx CLI](/influxdb/v2.1/tools/influx-cli/). +{{% /note %}} + +InfluxDB v{{< current-version >}} (Windows) + +Expand the downloaded archive into `C:\Program Files\InfluxData\` and rename the files if desired. + +```powershell +> Expand-Archive .\influxdb2-{{< latest-patch >}}-windows-amd64.zip -DestinationPath 'C:\Program Files\InfluxData\' +> mv 'C:\Program Files\InfluxData\influxdb2-{{< latest-patch >}}-windows-amd64' 'C:\Program Files\InfluxData\influxdb' +``` + +## Networking ports +By default, InfluxDB uses TCP port `8086` for client-server communication over +the [InfluxDB HTTP API](/influxdb/v2.1/reference/api/). + +## Start InfluxDB +In **Powershell**, navigate into `C:\Program Files\InfluxData\influxdb` and start +InfluxDB by running the `influxd` daemon: + +```powershell +> cd -Path 'C:\Program Files\InfluxData\influxdb' +> ./influxd +``` + +_See the [`influxd` documentation](/influxdb/v2.1/reference/cli/influxd) for information about +available flags and options._ + +{{% note %}} +#### Grant network access +When starting InfluxDB for the first time, **Windows Defender** will appear with +the following message: + +> Windows Defender Firewall has blocked some features of this app. + +1. Select **Private networks, such as my home or work network**. +2. Click **Allow access**. +{{% /note %}} + +{{% note %}} +#### InfluxDB "phone home" + +By default, InfluxDB sends telemetry data back to InfluxData. +The [InfluxData telemetry](https://www.influxdata.com/telemetry) page provides +information about what data is collected and how it is used. + +To opt-out of sending telemetry data back to InfluxData, include the +`--reporting-disabled` flag when starting `influxd`. + +```bash +./influxd --reporting-disabled +``` +{{% /note %}} + +{{% /tab-content %}} + + + +{{% tab-content %}} +## Download and run InfluxDB v{{< current-version >}} + +Use `docker run` to download and run the InfluxDB v{{< current-version >}} Docker image. +Expose port `8086`, which InfluxDB uses for client-server communication over +the [InfluxDB HTTP API](/influxdb/v2.1/reference/api/). + +```sh +docker run --name influxdb -p 8086:8086 influxdb:{{< latest-patch >}} +``` +_To run InfluxDB in [detached mode](https://docs.docker.com/engine/reference/run/#detached-vs-foreground), include the `-d` flag in the `docker run` command._ + +## Persist data outside the InfluxDB container + +1. Create a new directory to store your data in and navigate into the directory. + + ```sh + mkdir path/to/influxdb-docker-data-volume && cd $_ + ``` +2. From within your new directory, run the InfluxDB Docker container with the `--volume` flag to + persist data from `/var/lib/influxdb2` _inside_ the container to the current working directory in + the host file system. + + ```sh + docker run \ + --name influxdb \ + -p 8086:8086 \ + --volume $PWD:/var/lib/influxdb2 \ + influxdb:{{< latest-patch >}} + ``` + +## Configure InfluxDB with Docker + +To mount an InfluxDB configuration file and use it from within Docker: + +1. [Persist data outside the InfluxDB container](#persist-data-outside-the-influxdb-container). + +2. Use the command below to generate the default configuration file on the host file system: + + ```sh + docker run \ + --rm influxdb:{{< latest-patch >}} \ + influxd print-config > config.yml + ``` + +3. Modify the default configuration, which will now be available under `$PWD`. + +4. Start the InfluxDB container: + + ```sh + docker run -p 8086:8086 \ + -v $PWD/config.yml:/etc/influxdb2/config.yml \ + influxdb:{{< latest-patch >}} + ``` + +(Find more about configuring InfluxDB [here](https://docs.influxdata.com/influxdb/v2.1/reference/config-options/).) + +## Open a shell in the InfluxDB container + +To use the `influx` command line interface, open a shell in the `influxdb` Docker container: + +```sh +docker exec -it influxdb /bin/bash +``` + +{{% note %}} +#### InfluxDB "phone home" + +By default, InfluxDB sends telemetry data back to InfluxData. +The [InfluxData telemetry](https://www.influxdata.com/telemetry) page provides +information about what data is collected and how it is used. + +To opt-out of sending telemetry data back to InfluxData, include the +`--reporting-disabled` flag when starting the InfluxDB container. + +```sh +docker run -p 8086:8086 influxdb:{{< latest-patch >}} --reporting-disabled +``` +{{% /note %}} + +{{% /tab-content %}} + + + +{{% tab-content %}} + +## Install InfluxDB in a Kubernetes cluster + +The instructions below use **minikube** or **kind**, but the steps should be similar in any Kubernetes cluster. +InfluxData also makes [Helm charts](https://github.com/influxdata/helm-charts) available. + +1. Install [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) or + [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation). + +2. Start a local cluster: + + ```sh + # with minikube + minikube start + + # with kind + kind create cluster + ``` + +3. Apply the [sample InfluxDB configuration](https://github.com/influxdata/docs-v2/blob/master/static/downloads/influxdb-k8-minikube.yaml) by running: + + ```sh + kubectl apply -f https://raw.githubusercontent.com/influxdata/docs-v2/master/static/downloads/influxdb-k8-minikube.yaml + ``` + + This creates an `influxdb` Namespace, Service, and StatefulSet. + A PersistentVolumeClaim is also created to store data written to InfluxDB. + + **Important**: Always inspect YAML manifests before running `kubectl apply -f `! + +4. Ensure the Pod is running: + + ```sh + kubectl get pods -n influxdb + ``` + +5. Ensure the Service is available: + + ```sh + kubectl describe service -n influxdb influxdb + ``` + + You should see an IP address after `Endpoints` in the command's output. + +6. Forward port 8086 from inside the cluster to localhost: + + ```sh + kubectl port-forward -n influxdb service/influxdb 8086:8086 + ``` + +{{% /tab-content %}} + + +{{% tab-content %}} + +## Install InfluxDB v{{< current-version >}} on Raspberry Pi + +{{% note %}} +#### Requirements + +To run InfluxDB on Raspberry Pi, you need: + +- a Raspberry Pi 4+ or 400 +- a 64-bit operating system. + We recommend installing a [64-bit version of Ubuntu](https://ubuntu.com/download/raspberry-pi) + of Ubuntu Desktop or Ubuntu Server compatible with 64-bit Raspberry Pi. +{{% /note %}} + +### Install Linux binaries + +Follow the [Linux installation instructions](/influxdb/v2.1/install/?t=Linux) +to install InfluxDB on a Raspberry Pi. + +### Monitor your Raspberry Pi +Use the [InfluxDB Raspberry Pi template](/influxdb/cloud/monitor-alert/templates/infrastructure/raspberry-pi/) +to easily configure collecting and visualizing system metrics for the Raspberry Pi. + +#### Monitor 32-bit Raspberry Pi systems +If you have a 32-bit Raspberry Pi, [use Telegraf](/{{< latest "telegraf" >}}/) +to collect and send data to: + +- [InfluxDB OSS](/influxdb/v2.1/), running on a 64-bit system +- InfluxDB Cloud with a [**Free Tier**](/influxdb/cloud/account-management/pricing-plans/#free-plan) account +- InfluxDB Cloud with a paid [**Usage-Based**](/influxdb/cloud/account-management/pricing-plans/#usage-based-plan) account with relaxed resource restrictions. + +{{% /tab-content %}} + + +{{< /tabs-wrapper >}} + +## Download and install the influx CLI +The [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) lets you manage InfluxDB +from your command line. + +Download and install the influx CLI + +## Set up InfluxDB + +The initial setup process for InfluxDB walks through creating a default organization, +user, bucket, and Operator API token. +The setup process is available in both the InfluxDB user interface (UI) and in +the `influx` command line interface (CLI). + +{{% note %}} +#### Operator token permissions +The **Operator token** created in the InfluxDB setup process has +**full read and write access to all organizations** in the database. +To prevent accidental interactions across organizations, we recommend +[creating an All-Access token](/influxdb/v2.1/security/tokens/create-token/) +for each organization and using those to manage InfluxDB. +{{% /note %}} + +{{< tabs-wrapper >}} +{{% tabs %}} +[UI Setup](#) +[CLI Setup](#) +{{% /tabs %}} + + +{{% tab-content %}} +### Set up InfluxDB through the UI + +1. With InfluxDB running, visit [localhost:8086](http://localhost:8086). +2. Click **Get Started** + +#### Set up your initial user + +1. Enter a **Username** for your initial user. +2. Enter a **Password** and **Confirm Password** for your user. +3. Enter your initial **Organization Name**. +4. Enter your initial **Bucket Name**. +5. Click **Continue**. + +InfluxDB is now initialized with a primary user, organization, and bucket. +You are ready to [write or collect data](/influxdb/v2.1/write-data). + +### (Optional) Set up and use the influx CLI + +To avoid having to pass your InfluxDB +[API token](/influxdb/v2.1/security/tokens/) with each `influx` command, set up a configuration profile to store your credentials. To do this, complete the following steps: + +1. In a terminal, run the following command: + + ```sh + # Set up a configuration profile + influx config create -n default \ + -u http://localhost:8086 \ + -o example-org \ + -t mySuP3rS3cr3tT0keN \ + -a + ``` + + This configures a new profile named `default` and makes the profile active + so your `influx` CLI commands run against the specified InfluxDB instance. + For more detail, see [`influx config`](/influxdb/v2.1/reference/cli/influx/config/). + +2. Learn `influx` CLI commands. To see all available `influx` commands, type + `influx -h` or check out [influx - InfluxDB command line interface](/influxdb/v2.1/reference/cli/influx/). + +{{% /tab-content %}} + + + +{{% tab-content %}} +### Set up InfluxDB through the influx CLI + +Begin the InfluxDB setup process via the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) by running: + +```bash +influx setup +``` + +1. Enter a **primary username**. +2. Enter a **password** for your user. +3. **Confirm your password** by entering it again. +4. Enter a name for your **primary organization**. +5. Enter a name for your **primary bucket**. +6. Enter a **retention period** for your primary bucket—valid units are + nanoseconds (`ns`), microseconds (`us` or `µs`), milliseconds (`ms`), + seconds (`s`), minutes (`m`), hours (`h`), days (`d`), and weeks (`w`). + Enter nothing for an infinite retention period. +7. Confirm the details for your primary user, organization, and bucket. + +InfluxDB is now initialized with a primary user, organization, bucket, and API token. +InfluxDB also creates a configuration profile for you so that you don't have to +add your InfluxDB host, organization, and token to every command. +To view that config profile, use the [`influx config list`](/influxdb/v2.1/reference/cli/influx/config) command. + +To continue to use InfluxDB via the CLI, you need the API token created during setup. +To view the token, log into the UI with the credentials created above. +(For instructions, see [View tokens in the InfluxDB UI](/influxdb/v2.1/security/tokens/view-tokens/#view-tokens-in-the-influxdb-ui).) + +You are ready to [write or collect data](/influxdb/v2.1/write-data). + +{{% note %}} +To automate the setup process, use [flags](/influxdb/v2.1/reference/cli/influx/setup/#flags) +to provide the required information. +{{% /note %}} + +{{% /tab-content %}} + +{{< /tabs-wrapper >}} + +After you’ve installed InfluxDB, you’re ready to [get started working with your data in InfluxDB](/influxdb/v2.1/get-started/). diff --git a/content/influxdb/v2.1/monitor-alert/_index.md b/content/influxdb/v2.1/monitor-alert/_index.md new file mode 100644 index 0000000000..55e51e90e5 --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/_index.md @@ -0,0 +1,38 @@ +--- +title: Monitor data and send alerts +seotitle: Monitor data and send alerts +description: > + Monitor your time series data and send alerts by creating checks, notification + rules, and notification endpoints. Or use community templates to monitor supported environments. +menu: + influxdb_2_1: + name: Monitor & alert +weight: 7 +influxdb/v2.1/tags: [monitor, alert, checks, notification, endpoints] +--- + +Monitor your time series data and send alerts by creating checks, notification +rules, and notification endpoints. Or use [community templates to monitor](/influxdb/v2.1/monitor-alert/templates/) supported environments. + +## Overview + +1. A [check](/influxdb/v2.1/reference/glossary/#check) in InfluxDB queries data and assigns a status with a `_level` based on specific conditions. +2. InfluxDB stores the output of a check in the `statuses` measurement in the `_monitoring` system bucket. +3. [Notification rules](/influxdb/v2.1/reference/glossary/#notification-rule) check data in the `statuses` + measurement and, based on conditions set in the notification rule, send a message + to a [notification endpoint](/influxdb/v2.1/reference/glossary/#notification-endpoint). +4. InfluxDB stores notifications in the `notifications` measurement in the `_monitoring` system bucket. + +## Create an alert + +To get started, do the following: + +1. [Create checks](/influxdb/v2.1/monitor-alert/checks/create/) to monitor data and assign a status. +2. [Add notification endpoints](/influxdb/v2.1/monitor-alert/notification-endpoints/create/) + to send notifications to third parties. +3. [Create notification rules](/influxdb/v2.1/monitor-alert/notification-rules/create) to check + statuses and send notifications to your notifications endpoints. + +## Manage your monitoring and alerting pipeline + +{{< children >}} diff --git a/content/influxdb/v2.1/monitor-alert/checks/_index.md b/content/influxdb/v2.1/monitor-alert/checks/_index.md new file mode 100644 index 0000000000..ba1ef55e96 --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/checks/_index.md @@ -0,0 +1,19 @@ +--- +title: Manage checks +seotitle: Manage monitoring checks in InfluxDB +description: > + Checks in InfluxDB query data and apply a status or level to each data point based on specified conditions. +menu: + influxdb_2_1: + parent: Monitor & alert +weight: 101 +influxdb/v2.1/tags: [monitor, checks, notifications, alert] +related: + - /influxdb/v2.1/monitor-alert/notification-rules/ + - /influxdb/v2.1/monitor-alert/notification-endpoints/ +--- + +Checks in InfluxDB query data and apply a status or level to each data point based on specified conditions. +Learn how to create and manage checks: + +{{< children >}} diff --git a/content/influxdb/v2.1/monitor-alert/checks/create.md b/content/influxdb/v2.1/monitor-alert/checks/create.md new file mode 100644 index 0000000000..fa2fc808ad --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/checks/create.md @@ -0,0 +1,152 @@ +--- +title: Create checks +seotitle: Create monitoring checks in InfluxDB +description: > + Create a check in the InfluxDB UI. +menu: + influxdb_2_1: + parent: Manage checks +weight: 201 +related: + - /influxdb/v2.1/monitor-alert/notification-rules/ + - /influxdb/v2.1/monitor-alert/notification-endpoints/ +--- + +Create a check in the InfluxDB user interface (UI). +Checks query data and apply a status to each point based on specified conditions. + +## Parts of a check +A check consists of two parts – a query and check configuration. + +#### Check query +- Specifies the dataset to monitor. +- May include tags to narrow results. + +#### Check configuration +- Defines check properties, including the check interval and status message. +- Evaluates specified conditions and applies a status (if applicable) to each data point: + - `crit` + - `warn` + - `info` + - `ok` +- Stores status in the `_level` column. + +## Check types +There are two types of checks – a threshold check and a deadman check. + +#### Threshold check +A threshold check assigns a status based on a value being above, below, +inside, or outside of defined thresholds. + +#### Deadman check +A deadman check assigns a status to data when a series or group doesn't report +in a specified amount of time. + +## Create a check in the InfluxDB UI +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Click **{{< icon "plus" >}} Create** and select the [type of check](#check-types) to create. +3. Click **Name this check** in the top left corner and provide a unique name for the check. + +#### Configure the check query +1. Select the **bucket**, **measurement**, **field** and **tag sets** to query. +2. If creating a threshold check, select an **aggregate function**. + Aggregate functions aggregate data between the specified check intervals and + return a single value for the check to process. + + In the **Aggregate functions** column, select an interval from the interval drop-down list + (for example, "Every 5 minutes") and an aggregate function from the list of functions. + +3. Click **Submit** to run the query and preview the results. + To see the raw query results, click the **{{< icon "toggle" >}} View Raw Data** toggle. + +#### Configure the check +1. Click **2. Configure Check** near the top of the window. +2. In the **Properties** column, configure the following: + + ##### Schedule Every + Select the interval to run the check (for example, "Every 5 minutes"). + This interval matches the aggregate function interval for the check query. + _Changing the interval here will update the aggregate function interval._ + + ##### Offset + Delay the execution of a task to account for any late data. + Offset queries do not change the queried time range. + + {{% note %}}Your offset must be shorter than your [check interval](#schedule-every). + {{% /note %}} + + ##### Tags + Add custom tags to the query output. + Each custom tag appends a new column to each row in the query output. + The column label is the tag key and the column value is the tag value. + + Use custom tags to associate additional metadata with the check. + Common metadata tags across different checks lets you easily group and organize checks. + You can also use custom tags in [notification rules](/influxdb/v2.1/monitor-alert/notification-rules/create/). + +3. In the **Status Message Template** column, enter the status message template for the check. + Use [Flux string interpolation](/{{< latest "flux" >}}/spec/string-interpolation/) + to populate the message with data from the query. + + {{% note %}} +#### Flux only interpolates string values +Flux currently interpolates only string values. +Use the [string() function](/{{< latest "flux" >}}/stdlib/universe/string/) +to convert non-string values to strings. + +```js +count = 12 +"I currently have ${string(v: count)} cats." +``` + {{% /note %}} + + Check data is represented as a record, `r`. + Access specific column values using dot notation: `r.columnName`. + + Use data from the following columns: + + - columns included in the query output + - [custom tags](#tags) added to the query output + - `_check_id` + - `_check_name` + - `_level` + - `_source_measurement` + - `_type` + + ###### Example status message template + ``` + From ${r._check_name}: + ${r._field} is ${r._level}. + Its value is ${string(v: r.field_name)}. + ``` + + When a check generates a status, it stores the message in the `_message` column. + +4. Define check conditions that assign statuses to points. + Condition options depend on your check type. + + ##### Configure a threshold check + 1. In the **Thresholds** column, click the status name (CRIT, WARN, INFO, or OK) + to define conditions for that specific status. + 2. From the **When value** drop-down list, select a threshold: is above, is below, + is inside of, is outside of. + 3. Enter a value or values for the threshold. + You can also use the threshold sliders in the data visualization to define threshold values. + + ##### Configure a deadman check + 1. In the **Deadman** column, enter a duration for the deadman check in the **for** field. + For example, `90s`, `5m`, `2h30m`, etc. + 2. Use the **set status to** drop-down list to select a status to set on a dead series. + 3. In the **And stop checking after** field, enter the time to stop monitoring the series. + For example, `30m`, `2h`, `3h15m`, etc. + +5. Click the green **{{< icon "check" >}}** in the top right corner to save the check. + +## Clone a check +Create a new check by cloning an existing check. + +1. In the **Checks** column, hover over the check you want to clone. +2. Click the **{{< icon "clone" >}}** icon, then **Clone**. diff --git a/content/influxdb/v2.1/monitor-alert/checks/delete.md b/content/influxdb/v2.1/monitor-alert/checks/delete.md new file mode 100644 index 0000000000..a682afd4f1 --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/checks/delete.md @@ -0,0 +1,34 @@ +--- +title: Delete checks +seotitle: Delete monitoring checks in InfluxDB +description: > + Delete checks in the InfluxDB UI. +menu: + influxdb_2_1: + parent: Manage checks +weight: 204 +related: + - /influxdb/v2.1/monitor-alert/notification-rules/ + - /influxdb/v2.1/monitor-alert/notification-endpoints/ +--- + +If you no longer need a check, use the InfluxDB user interface (UI) to delete it. + +{{% warn %}} +Deleting a check cannot be undone. +{{% /warn %}} + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Hover over the check you want to delete, click the **{{< icon "delete" >}}** + icon, and then **Delete**. + +After a check is deleted, all statuses generated by the check remain in the `_monitoring` +bucket until the retention period for the bucket expires. + +{{% note %}} +You can also [disable a check](/influxdb/v2.1/monitor-alert/checks/update/#enable-or-disable-a-check) +without having to delete it. +{{% /note %}} diff --git a/content/influxdb/v2.1/monitor-alert/checks/update.md b/content/influxdb/v2.1/monitor-alert/checks/update.md new file mode 100644 index 0000000000..a62a8d020a --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/checks/update.md @@ -0,0 +1,60 @@ +--- +title: Update checks +seotitle: Update monitoring checks in InfluxDB +description: > + Update, rename, enable or disable checks in the InfluxDB UI. +menu: + influxdb_2_1: + parent: Manage checks +weight: 203 +related: + - /influxdb/v2.1/monitor-alert/notification-rules/ + - /influxdb/v2.1/monitor-alert/notification-endpoints/ +--- + +Update checks in the InfluxDB user interface (UI). +Common updates include: + +- [Update check queries and logic](#update-check-queries-and-logic) +- [Enable or disable a check](#enable-or-disable-a-check) +- [Rename a check](#rename-a-check) +- [Add or update a check description](#add-or-update-a-check-description) +- [Add a label to a check](#add-a-label-to-a-check) + +To update checks, select **Alerts** in the navigation menu on the left. + +{{< nav-icon "alerts" >}} + + +## Update check queries and logic +1. Click the name of the check you want to update. The check builder appears. +2. To edit the check query, click **1. Define Query** at the top of the check builder window. +3. To edit the check logic, click **2. Configure Check** at the top of the check builder window. + +_For details about using the check builder, see [Create checks](/influxdb/v2.1/monitor-alert/checks/create/)._ + +## Enable or disable a check +Click the {{< icon "toggle" >}} toggle next to a check to enable or disable it. + +## Rename a check +1. Hover over the name of the check you want to update. +2. Click the **{{< icon "edit" >}}** icon that appears next to the check name. +2. Enter a new name and click out of the name field or press enter to save. + +_You can also rename a check in the [check builder](#update-check-queries-and-logic)._ + +## Add or update a check description +1. Hover over the check description you want to update. +2. Click the **{{< icon "edit" >}}** icon that appears next to the description. +2. Enter a new description and click out of the name field or press enter to save. + +## Add a label to a check +1. Click **Add a label** next to the check you want to add a label to. + The **Add Labels** box opens. +2. To add an existing label, select the label from the list. +3. To create and add a new label: + - In the search field, enter the name of the new label. The **Create Label** box opens. + - In the **Description** field, enter an optional description for the label. + - Select a color for the label. + - Click **Create Label**. +4. To remove a label, hover over the label under to a rule and click **{{< icon "x" >}}**. diff --git a/content/influxdb/v2.1/monitor-alert/checks/view.md b/content/influxdb/v2.1/monitor-alert/checks/view.md new file mode 100644 index 0000000000..8b826845ee --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/checks/view.md @@ -0,0 +1,43 @@ +--- +title: View checks +seotitle: View monitoring checks in InfluxDB +description: > + View check details and statuses and notifications generated by checks in the InfluxDB UI. +menu: + influxdb_2_1: + parent: Manage checks +weight: 202 +related: + - /influxdb/v2.1/monitor-alert/notification-rules/ + - /influxdb/v2.1/monitor-alert/notification-endpoints/ +--- + +View check details and statuses and notifications generated by checks in the InfluxDB user interface (UI). + +- [View a list of all checks](#view-a-list-of-all-checks) +- [View check details](#view-check-details) +- [View statuses generated by a check](#view-statuses-generated-by-a-check) +- [View notifications triggered by a check](#view-notifications-triggered-by-a-check) + +To view checks, click **Alerts** in navigation menu on the left. + +{{< nav-icon "alerts" >}} + +## View a list of all checks +The **Checks** section of the Alerts landing page displays all existing checks. + +## View check details +Click the name of the check you want to view. +The check builder appears. +Here you can view the check query and logic. + +## View statuses generated by a check +1. Hover over the check and click the **{{< icon "view" >}}** icon. +2. Click **View History**. + The Statuses History page displays statuses generated by the selected check. + +## View notifications triggered by a check +1. Hover over the check, click the **{{< icon "view" >}}** + icon, then **View History**. +2. In the top left corner, click **Notifications**. + The Notifications History page displays notifications initiated by the selected check. diff --git a/content/influxdb/v2.1/monitor-alert/custom-checks.md b/content/influxdb/v2.1/monitor-alert/custom-checks.md new file mode 100644 index 0000000000..39f92cffbc --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/custom-checks.md @@ -0,0 +1,102 @@ +--- +title: Create custom checks +seotitle: Custom checks +description: > + Create custom checks with a Flux task. +menu: + influxdb_2_1: + parent: Monitor & alert +weight: 201 +influxdb/v2.1/tags: [alerts, checks, tasks, Flux] +--- + +In the UI, you can create two kinds of [checks](/influxdb/v2.1/reference/glossary/#check): +[`threshold`](/influxdb/v2.1/monitor-alert/checks/create/#threshold-check) and +[`deadman`](/influxdb/v2.1/monitor-alert/checks/create/#deadman-check). + +Using a Flux task, you can create a custom check that provides a couple advantages: + +- Customize and transform the data you would like to use for the check. +- Set up custom criteria for your alert (other than `threshold` and `deadman`). + +## Create a task + +1. In the InfluxDB UI, select **Tasks** in the navigation menu on the left. + + {{< nav-icon "tasks" >}} + +2. Click **{{< icon "plus" >}} Create Task**, and then select **New Task**. +3. In the **Name** field, enter a descriptive name, + and then enter how often to run the task in the **Every** field (for example, `10m`). + For more detail, such as using cron syntax or including an offset, see [Task configuration options](/influxdb/v2.1/process-data/task-options/). +4. Enter the Flux script for your custom check, including the [`monitor.check`](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/monitor/check/) function. + +{{% note %}} +Use the the API endpoint `/checks/{checkID}/query` to see the Flux code for a check built in the UI. +This can be useful for constructing custom checks. +{{% /note %}} + +### Example: Monitor failed tasks + +The script below is fairly complex, and can be used as a framework for similar tasks. +It does the following: + +- Import the necessary `influxdata/influxdb/monitor` package, and other packages for data processing. +- Query the `_tasks` bucket to retrieve all statuses generated by your check. +- Set the `_level` to alert on, for example, `crit`, `warn`, `info`, or `ok`. +- Create a `check` object that specifies an ID, name, and type for the check. +- Define the `ok` and `crit` statuses. +- Execute the `monitor` function on the `check` using the `task_data`. + +#### Example alert task script + +```js +import "strings" +import "regexp" +import "influxdata/influxdb/monitor" +import "influxdata/influxdb/schema" + +option task = {name: "Failed Tasks Check", every: 1h, offset: 4m} + +task_data = from(bucket: "_tasks") + |> range(start: -task.every) + |> filter(fn: (r) => + (r["_measurement"] == "runs")) + |> filter(fn: (r) => + (r["_field"] == "logs")) + |> map(fn: (r) => ({ r with name: strings.split(v: regexp.findString(r: /option task = \{([^\}]+)/, v: r._value), t: "\\\\\\\"")[1] })) + |> drop(columns: ["_value", "_start", "_stop"]) + |> group(columns: ["name", "taskID", "status", "_measurement"]) + |> map(fn: (r) => + ({r with _value: if r.status == "failed" then 1 else 0})) + |> last() +check = { + _check_id: "0000000000000001", // 16 characters, alphanumeric + _check_name: "Failed Tasks Check", // string + _type: "custom", // can also use "threshold" or "deadman" + tags: {}, +} +ok = (r) => + (r["logs"] == 0) +crit = (r) => + (r["logs"] == 1) +messageFn = (r) => + ("The task: ${r.taskID} - ${r.name} has a status of ${r.status}") + +task_data + |> schema["fieldsAsCols"]() + |> monitor["check"]( + data: check, + messageFn: messageFn, + ok: ok, + crit: crit, + ) +``` + +{{% note %}} +Creating a custom check does not send a notification email. +For information on how to create notification emails, see +[Create notification endpoints](/influxdb/v2.1/monitor-alert/notification-endpoints/create), +[Create notification rules](/influxdb/v2.1/monitor-alert/notification-rules/create), +and [Send alert email](/influxdb/v2.1/monitor-alert/send-email/) +{{% /note %}} diff --git a/content/influxdb/v2.1/monitor-alert/notification-endpoints/_index.md b/content/influxdb/v2.1/monitor-alert/notification-endpoints/_index.md new file mode 100644 index 0000000000..ee25e5c366 --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/notification-endpoints/_index.md @@ -0,0 +1,19 @@ +--- +title: Manage notification endpoints +list_title: Manage notification endpoints +description: > + Create, read, update, and delete endpoints in the InfluxDB UI. +influxdb/v2.1/tags: [monitor, endpoints, notifications, alert] +menu: + influxdb_2_1: + parent: Monitor & alert +weight: 102 +related: + - /influxdb/v2.1/monitor-alert/checks/ + - /influxdb/v2.1/monitor-alert/notification-rules/ +--- + +Notification endpoints store information to connect to a third-party service. +Create a connection to a HTTP, Slack, or PagerDuty endpoint. + +{{< children >}} diff --git a/content/influxdb/v2.1/monitor-alert/notification-endpoints/create.md b/content/influxdb/v2.1/monitor-alert/notification-endpoints/create.md new file mode 100644 index 0000000000..236f6fdece --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/notification-endpoints/create.md @@ -0,0 +1,41 @@ +--- +title: Create notification endpoints +description: > + Create notification endpoints to send alerts on your time series data. +menu: + influxdb_2_1: + name: Create endpoints + parent: Manage notification endpoints +weight: 201 +related: + - /influxdb/v2.1/monitor-alert/checks/ + - /influxdb/v2.1/monitor-alert/notification-rules/ +--- + +To send notifications about changes in your data, start by creating a notification endpoint to a third-party service. After creating notification endpoints, [create notification rules](/influxdb/v2.1/monitor-alert/notification-rules/create) to send alerts to third-party services on [check statuses](/influxdb/v2.1/monitor-alert/checks/create). + +## Create a notification endpoint in the UI + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. +3. Click **{{< icon "plus" >}} Create**. +4. From the **Destination** drop-down list, select a destination endpoint to send notifications +5. In the **Name** and **Description** fields, enter a name and description for the endpoint. +6. Enter information to connect to the endpoint: + + - For HTTP, enter the **URL** to send the notification. Select the **auth method** to use: **None** for no authentication. To authenticate with a username and password, select **Basic** and then enter credentials in the **Username** and **Password** fields. To authenticate with an API token, select **Bearer**, and then enter the API token in the **Token** field. + + - **For Slack**, create an [Incoming WebHook](https://api.slack.com/incoming-webhooks#posting_with_webhooks) in Slack, and then enter your webHook URL in the **Slack Incoming WebHook URL** field. + + - **For PagerDuty**: + - [Create a new service](https://support.pagerduty.com/docs/services-and-integrations#section-create-a-new-service), [add an integration for your service](https://support.pagerduty.com/docs/services-and-integrations#section-add-integrations-to-an-existing-service), and then enter the PagerDuty integration key for your new service in the **Routing Key** field. + - The **Client URL** provides a useful link in your PagerDuty notification. Enter any URL that you'd like to use to investigate issues. This URL is sent as the `client_url` property in the PagerDuty trigger event. By default, the **Client URL** is set to your Monitoring & Alerting History page, and the following included in the PagerDuty trigger event: + + ```json + "client_url": "http://localhost:8086/orgs//alert-history" + ``` + +6. Click **Create Notification Endpoint**. diff --git a/content/influxdb/v2.1/monitor-alert/notification-endpoints/delete.md b/content/influxdb/v2.1/monitor-alert/notification-endpoints/delete.md new file mode 100644 index 0000000000..29fbe5fff9 --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/notification-endpoints/delete.md @@ -0,0 +1,26 @@ +--- +title: Delete notification endpoints +description: > + Delete a notification endpoint in the InfluxDB UI. +menu: + influxdb_2_1: + name: Delete endpoints + parent: Manage notification endpoints +weight: 204 +related: + - /influxdb/v2.1/monitor-alert/checks/ + - /influxdb/v2.1/monitor-alert/notification-rules/ +--- + +If notifications are no longer sent to an endpoint, complete the steps below to delete the endpoint, and then [update notification rules](/influxdb/v2.1/monitor-alert/notification-rules/update) with a new notification endpoint as needed. + +## Delete a notification endpoint in the UI + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. + find the rule you want to delete. +3. Hover over the endpoint you want to delete and click the **{{< icon "trash" >}}** icon. +4. Click **Delete** to confirm. diff --git a/content/influxdb/v2.1/monitor-alert/notification-endpoints/update.md b/content/influxdb/v2.1/monitor-alert/notification-endpoints/update.md new file mode 100644 index 0000000000..2ff6e165af --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/notification-endpoints/update.md @@ -0,0 +1,66 @@ +--- +title: Update notification endpoints +description: > + Update notification endpoints in the InfluxDB UI. +menu: + influxdb_2_1: + name: Update endpoints + parent: Manage notification endpoints +weight: 203 +related: + - /influxdb/v2.1/monitor-alert/checks/ + - /influxdb/v2.1/monitor-alert/notification-rules/ +--- + +To update the notification endpoint details, complete the procedures below as needed. To update the notification endpoint selected for a notification rule, see [update notification rules](/influxdb/v2.1/monitor-alert/notification-rules/update/). + +## Add a label to notification endpoint + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. +3. Click **{{< icon "add-label" >}} Add a label** next to the endpoint you want to add a label to. + The **Add Labels** box opens. +4. To add an existing label, select the label from the list. +5. To create and add a new label: + + - In the search field, enter the name of the new label. The **Create Label** box opens. + - In the **Description** field, enter an optional description for the label. + - Select a color for the label. + - Click **Create Label**. + +6. To remove a label, hover over the label under an endpoint and click X. + + +## Disable notification endpoint + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. +3. Click the {{< icon "toggle" >}} toggle to disable the notification endpoint. + +## Update the name or description for notification endpoint + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. +3. Hover over the name or description of the endpoint and click the pencil icon + (**{{< icon "edit" >}}**) to edit the field. +4. Click outside of the field to save your changes. + +## Change endpoint details + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. +3. Click the endpoint to update. +4. Update details as needed, and then click **Edit Notification Endpoint**. + For details about each field, see [Create notification endpoints](/influxdb/v2.1/monitor-alert/notification-endpoints/create/). diff --git a/content/influxdb/v2.1/monitor-alert/notification-endpoints/view.md b/content/influxdb/v2.1/monitor-alert/notification-endpoints/view.md new file mode 100644 index 0000000000..687c856405 --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/notification-endpoints/view.md @@ -0,0 +1,51 @@ +--- +title: View notification endpoint history +seotitle: View notification endpoint details and history +description: > + View notification endpoint details and history in the InfluxDB UI. +menu: + influxdb_2_1: + name: View endpoint history + parent: Manage notification endpoints +weight: 202 +related: + - /influxdb/v2.1/monitor-alert/checks/ + - /influxdb/v2.1/monitor-alert/notification-rules/ +--- + +View notification endpoint details and history in the InfluxDB user interface (UI). + +- [View notification endpoints](#view-notification-endpoints) +- [View notification endpoint details](#view-notification-endpoint-details) +- [View history notification endpoint history](#view-notification-endpoint-history), including statues and notifications sent to the endpoint + +## View notification endpoints + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. + +## View notification endpoint details + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. +3. Click the name of the notification endpoint you want to view. +4. View the notification endpoint destination, name, and information to connect to the endpoint. + +## View notification endpoint history + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. +3. Hover over the notification endpoint, click the **{{< icon "view" >}}** icon, then **View History**. + The Check Statuses History page displays: + + - Statuses generated for the selected notification endpoint + - Notifications sent to the selected notification endpoint diff --git a/content/influxdb/v2.1/monitor-alert/notification-rules/_index.md b/content/influxdb/v2.1/monitor-alert/notification-rules/_index.md new file mode 100644 index 0000000000..e3c02b97a5 --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/notification-rules/_index.md @@ -0,0 +1,17 @@ +--- +title: Manage notification rules +description: > + Manage notification rules in InfluxDB. +weight: 103 +influxdb/v2.1/tags: [monitor, notifications, alert] +menu: + influxdb_2_1: + parent: Monitor & alert +related: + - /influxdb/v2.1/monitor-alert/checks/ + - /influxdb/v2.1/monitor-alert/notification-endpoints/ +--- + +The following articles provide information on managing your notification rules: + +{{< children >}} diff --git a/content/influxdb/v2.1/monitor-alert/notification-rules/create.md b/content/influxdb/v2.1/monitor-alert/notification-rules/create.md new file mode 100644 index 0000000000..bc94e8dc55 --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/notification-rules/create.md @@ -0,0 +1,44 @@ +--- +title: Create notification rules +description: > + Create notification rules to send alerts on your time series data. +weight: 201 +menu: + influxdb_2_1: + parent: Manage notification rules +related: + - /influxdb/v2.1/monitor-alert/checks/ + - /influxdb/v2.1/monitor-alert/notification-endpoints/ +--- + +Once you've set up checks and notification endpoints, create notification rules to alert you. +_For details, see [Manage checks](/influxdb/v2.1/monitor-alert/checks/) and +[Manage notification endpoints](/influxdb/v2.1/monitor-alert/notification-endpoints/)._ + +## Create a new notification rule in the UI + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Rules** near to top of the page. +3. Click **{{< icon "plus" >}} Create**. +4. Complete the **About** section: + 1. In the **Name** field, enter a name for the notification rule. + 2. In the **Schedule Every** field, enter how frequently the rule should run. + 3. In the **Offset** field, enter an offset time. For example,if a task runs on the hour, a 10m offset delays the task to 10 minutes after the hour. Time ranges defined in the task are relative to the specified execution time. +5. In the **Conditions** section, build a condition using a combination of status and tag keys. + - Next to **When status is equal to**, select a status from the drop-down field. + - Next to **AND When**, enter one or more tag key-value pairs to filter by. +6. In the **Message** section, select an endpoint to notify. +7. Click **Create Notification Rule**. + +## Clone an existing notification rule in the UI + +1. 1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Rules** near to top of the page. +3. Hover over the rule you want to clone and click the **{{< icon "clone" >}}** icon and select **Clone**. + The cloned rule appears. diff --git a/content/influxdb/v2.1/monitor-alert/notification-rules/delete.md b/content/influxdb/v2.1/monitor-alert/notification-rules/delete.md new file mode 100644 index 0000000000..e6dd0a572f --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/notification-rules/delete.md @@ -0,0 +1,22 @@ +--- +title: Delete notification rules +description: > + If you no longer need to receive an alert, delete the associated notification rule. +weight: 204 +menu: + influxdb_2_1: + parent: Manage notification rules +related: + - /influxdb/v2.1/monitor-alert/checks/ + - /influxdb/v2.1/monitor-alert/notification-endpoints/ +--- + +## Delete a notification rule in the UI + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Rules** near to top of the page. +3. Hover over the rule you want to delete and click the **{{< icon "trash" >}}** icon. +4. Click **Delete** to confirm. diff --git a/content/influxdb/v2.1/monitor-alert/notification-rules/update.md b/content/influxdb/v2.1/monitor-alert/notification-rules/update.md new file mode 100644 index 0000000000..87b1abf77a --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/notification-rules/update.md @@ -0,0 +1,50 @@ +--- +title: Update notification rules +description: > + Update notification rules to update the notification message or change the schedule or conditions. +weight: 203 +menu: + influxdb_2_1: + parent: Manage notification rules +related: + - /influxdb/v2.1/monitor-alert/checks/ + - /influxdb/v2.1/monitor-alert/notification-endpoints/ +--- + +## Add a label to notification rules + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Rules** near to top of the page. +3. Click **{{< icon "add-label" >}} Add a label** next to the rule you want to add a label to. + The **Add Labels** box opens. +4. To add an existing label, select the label from the list. +5. To create and add a new label: + - In the search field, enter the name of the new label. The **Create Label** box opens. + - In the **Description** field, enter an optional description for the label. + - Select a color for the label. + - Click **Create Label**. +6. To remove a label, hover over the label under to a rule and click **{{< icon "x" >}}**. + + +## Disable notification rules + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Rules** near to top of the page. +3. Click the {{< icon "toggle" >}} toggle to disable the notification rule. + +## Update the name or description for notification rules + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Rules** near to top of the page. +3. Hover over the name or description of a rule and click the pencil icon + (**{{< icon "edit" >}}**) to edit the field. +4. Click outside of the field to save your changes. diff --git a/content/influxdb/v2.1/monitor-alert/notification-rules/view.md b/content/influxdb/v2.1/monitor-alert/notification-rules/view.md new file mode 100644 index 0000000000..c29447662d --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/notification-rules/view.md @@ -0,0 +1,45 @@ +--- +title: View notification rules +description: > + Update notification rules to update the notification message or change the schedule or conditions. +weight: 202 +menu: + influxdb_2_1: + parent: Manage notification rules +related: + - /influxdb/v2.1/monitor-alert/checks/ + - /influxdb/v2.1/monitor-alert/notification-endpoints/ +--- + +View notification rule details and statuses and notifications generated by notification rules in the InfluxDB user interface (UI). + +- [View a list of all notification rules](#view-a-list-of-all-notification-rules) +- [View notification rule details](#view-notification-rule-details) +- [View statuses generated by a check](#view-statuses-generated-by-a-notification-rule) +- [View notifications triggered by a notification rule](#view-notifications-triggered-by-a-notification-rule) + +**To view notification rules:** + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Rules** near to top of the page. + +## View a list of all notification rules +The **Notification Rules** section of the Alerts landing page displays all existing checks. + +## View notification rule details +Click the name of the check you want to view. +The check builder appears. +Here you can view the check query and logic. + +## View statuses generated by a notification rule +Hover over the check, click the **{{< icon "view" >}}** icon, and then **View History**. +The Statuses History page displays statuses generated by the selected check. + +## View notifications triggered by a notification rule +1. Hover over the notification rule, click the **{{< icon "view" >}}** + icon, and then **View History**. +2. In the top left corner, click **Notifications**. + The Notifications History page displays notifications initiated by the selected notification rule. diff --git a/content/influxdb/v2.1/monitor-alert/send-email.md b/content/influxdb/v2.1/monitor-alert/send-email.md new file mode 100644 index 0000000000..bc7427e545 --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/send-email.md @@ -0,0 +1,273 @@ +--- +title: Send alert email +description: > + Send an alert email. +menu: + influxdb_2_1: + parent: Monitor & alert +weight: 104 +influxdb/v2.1/tags: [alert, email, notifications, check] +related: + - /influxdb/v2.1/monitor-alert/checks/ +--- + +Send an alert email using a third-party service, such as [SendGrid](https://sendgrid.com/), [Amazon Simple Email Service (SES)](https://aws.amazon.com/ses/), [Mailjet](https://www.mailjet.com/), or [Mailgun](https://www.mailgun.com/). To send an alert email, complete the following steps: + +1. [Create a check](/influxdb/v2.1/monitor-alert/checks/create/#create-a-check-in-the-influxdb-ui) to identify the data to monitor and the status to alert on. +2. Set up your preferred email service (sign up, retrieve API credentials, and send test email): + - **SendGrid**: See [Getting Started With the SendGrid API](https://sendgrid.com/docs/API_Reference/api_getting_started.html) + - **AWS Simple Email Service (SES)**: See [Using the Amazon SES API](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email.html). Your AWS SES request, including the `url` (endpoint), authentication, and the structure of the request may vary. For more information, see [Amazon SES API requests](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-requests.html) and [Authenticating requests to the Amazon SES API](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-authentication.html). + - **Mailjet**: See [Getting Started with Mailjet](https://dev.mailjet.com/email/guides/getting-started/) + - **Mailgun**: See [Mailgun Signup](https://signup.mailgun.com/new/signup) +3. [Create an alert email task](#create-an-alert-email-task) to call your email service and send an alert email. + + {{% note %}} + In the procedure below, we use the **Task** page in the InfluxDB UI (user interface) to create a task. Explore other ways to [create a task](/influxdb/v2.1/process-data/manage-tasks/create-task/). + {{% /note %}} + +### Create an alert email task + +1. In the InfluxDB UI, select **Tasks** in the navigation menu on the left. + + {{< nav-icon "tasks" >}} + +2. Click **{{< icon "plus" >}} Create Task**, and then select **New Task**. +3. In the **Name** field, enter a descriptive name, for example, **Send alert email**, and then enter how often to run the task in the **Every** field, for example, `10m`. For more detail, such as using cron syntax or including an offset, see [Task configuration options](/influxdb/v2.1/process-data/task-options/). + +4. In the right panel, enter the following detail in your **task script** (see [examples below](#examples)): + - Import the [Flux HTTP package](/{{< latest "flux" >}}/stdlib/http/). + - (Optional) Store your API key as a secret for reuse. First, [add your API key as a secret](/influxdb/v2.1/security/secrets/manage-secrets/add/), and then import the [Flux InfluxDB Secrets package](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/secrets/). + - Query the `statuses` measurement in the `_monitoring` bucket to retrieve all statuses generated by your check. + - Set the time range to monitor; use the same interval that the task is scheduled to run. For example, `range (start: -task.every)`. + - Set the `_level` to alert on, for example, `crit`, `warn`, `info`, or `ok`. + - Use the `map()` function to evaluate the criteria to send an alert using `http.post()`. + - Specify your email service `url` (endpoint), include applicable request `headers`, and verify your request `data` format follows the format specified for your email service. + +#### Examples + +{{< tabs-wrapper >}} +{{% tabs %}} +[SendGrid](#) +[AWS SES](#) +[Mailjet](#) +[Mailgun](#) +{{% /tabs %}} + + +{{% tab-content %}} + +The example below uses the SendGrid API to send an alert email when more than 3 critical statuses occur since the previous task run. + +```js +import "http" +import "json" + +// Import the Secrets package if you store your API key as a secret. +// For detail on how to do this, see Step 4 above. +import "influxdata/influxdb/secrets" + +// Retrieve the secret if applicable. Otherwise, skip this line +// and add the API key as the Bearer token in the Authorization header. +SENDGRID_APIKEY = secrets.get(key: "SENDGRID_APIKEY") + +numberOfCrits = from(bucket: "_monitoring") + |> range(start: -task.every) + |> filter(fn: (r) => r._measurement == "statuses" and r._level == "crit") + |> count() + +numberOfCrits + |> map(fn: (r) => (if r._value > 3 then { + r with _value: http.post( + url: "https://api.sendgrid.com/v3/mail/send", + headers: { + "Content-Type": "application/json", + "Authorization": "Bearer ${SENDGRID_APIKEY}" + }, + data: json.encode(v: { + "personalizations": [ + { + "to": [ + { + "email": "jane.doe@example.com" + } + ] + } + ], + "from": { + "email": "john.doe@example.com" + }, + "subject": "InfluxDB critical alert", + "content": [ + { + "type": "text/plain", + "value": "There have been ${r._value} critical statuses." + } + ] + }))} else {r with _value: 0})) +``` + +{{% /tab-content %}} + + +{{% tab-content %}} + +The example below uses the AWS SES API v2 to send an alert email when more than 3 critical statuses occur since the last task run. + +{{% note %}} +Your AWS SES request, including the `url` (endpoint), authentication, and the structure of the request may vary. For more information, see [Amazon SES API requests](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-requests.html) and [Authenticating requests to the Amazon SES API](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-authentication.html). We recommend signing your AWS API requests using the [Signature Version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html). +{{% /note %}} + +```js +import "http" +import "json" + +// Import the Secrets package if you store your API credentials as secrets. +// For detail on how to do this, see Step 4 above. +import "influxdata/influxdb/secrets" + +// Retrieve the secrets if applicable. Otherwise, skip this line +// and add the API key as the Bearer token in the Authorization header. +AWS_AUTH_ALGORITHM = secrets.get(key: "AWS_AUTH_ALGORITHM") +AWS_CREDENTIAL = secrets.get(key: "AWS_CREDENTIAL") +AWS_SIGNED_HEADERS = secrets.get(key: "AWS_SIGNED_HEADERS") +AWS_CALCULATED_SIGNATURE = secrets.get(key: "AWS_CALCULATED_SIGNATURE") + +numberOfCrits = from(bucket: "_monitoring") + |> range(start: -task.every) + |> filter(fn: (r) => r.measurement == "statuses" and r._level == "crit") + |> count() + +numberOfCrits + |> map(fn: (r) => (if r._value > 3 then { + r with _value: http.post( + url: "https://email.your-aws-region.amazonaws.com/sendemail/v2/email/outbound-emails", + headers: { + "Content-Type": "application/json", + "Authorization": "Bearer ${AWS_AUTH_ALGORITHM}${AWS_CREDENTIAL}${AWS_SIGNED_HEADERS}${AWS_CALCULATED_SIGNATURE}" + }, + data: json.encode(v: { + "Content": { + "Simple": { + "Body": { + "Text": { + "Charset": "UTF-8", + "Data": "There have been ${r._value} critical statuses." + } + }, + "Subject": { + "Charset": "UTF-8", + "Data": "InfluxDB critical alert" + } + } + }, + "Destination": { + "ToAddresses": [ + "john.doe@example.com" + ] + } + }))} else {r with _value: 0})) +``` + +For details on the request syntax, see [SendEmail API v2 reference](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html). + +{{% /tab-content %}} + + +{{% tab-content %}} + +The example below uses the Mailjet Send API to send an alert email when more than 3 critical statuses occur since the last task run. + +{{% note %}} +To view your Mailjet API credentials, sign in to Mailjet and open the [API Key Management page](https://app.mailjet.com/account/api_keys). +{{% /note %}} + +```js +import "http" +import "json" + +// Import the Secrets package if you store your API keys as secrets. +// For detail on how to do this, see Step 4 above. +import "influxdata/influxdb/secrets" + +// Retrieve the secrets if applicable. Otherwise, skip this line +// and add the API keys as Basic credentials in the Authorization header. +MAILJET_APIKEY = secrets.get(key: "MAILJET_APIKEY") +MAILJET_SECRET_APIKEY = secrets.get(key: "MAILJET_SECRET_APIKEY") + +numberOfCrits = from(bucket: "_monitoring") + |> range(start: -task.every) + |> filter(fn: (r) => r.measurement == "statuses" and "r.level" == "crit") + |> count() + +numberOfCrits + |> map(fn: (r) => (if r._value > 3 then { + r with _value: http.post( + url: "https://api.mailjet.com/v3.1/send", + headers: { + "Content-type": "application/json", + "Authorization": "Basic ${MAILJET_APIKEY}:${MAILJET_SECRET_APIKEY}" + }, + data: json.encode(v: { + "Messages": [{ + "From": { + "Email": "jane.doe@example.com" + }, + "To": [{ + "Email": "john.doe@example.com" + }], + "Subject": "InfluxDB critical alert", + "TextPart": "There have been ${r._value} critical statuses.", + "HTMLPart": "

    ${r._value} critical statuses

    There have been ${r._value} critical statuses." + }] + }))} else {r with _value: 0})) +``` + +{{% /tab-content %}} + + + +{{% tab-content %}} + +The example below uses the Mailgun API to send an alert email when more than 3 critical statuses occur since the last task run. + +{{% note %}} +To view your Mailgun API keys, sign in to Mailjet and open [Account Security - API security](https://app.mailgun.com/app/account/security/api_keys). Mailgun requires that a domain be specified via Mailgun. A domain is automatically created for you when you first set up your account. You must include this domain in your `url` endpoint (for example, `https://api.mailgun.net/v3/YOUR_DOMAIN` or `https://api.eu.mailgun.net/v3/YOUR_DOMAIN`. If you're using a free version of Mailgun, you can set up a maximum of five authorized recipients (to receive email alerts) for your domain. To view your Mailgun domains, sign in to Mailgun and view the [Domains page](https://app.mailgun.com/app/sending/domains). +{{% /note %}} + +```js +import "http" +import "json" + +// Import the Secrets package if you store your API key as a secret. +// For detail on how to do this, see Step 4 above. +import "influxdata/influxdb/secrets" + +// Retrieve the secret if applicable. Otherwise, skip this line +// and add the API key as the Bearer token in the Authorization header. +MAILGUN_APIKEY = secrets.get(key: "MAILGUN_APIKEY") + +numberOfCrits = from(bucket: "_monitoring") + |> range(start: -task.every) + |> filter(fn: (r) => (r["_measurement"] == "statuses")) + |> filter(fn: (r) => (r["_level"] == "crit")) + |> count() + +numberOfCrits + |> map(fn: (r) => + (if r._value > 1 then {r with _value: http.post( + url: "https://api.mailgun.net/v3/YOUR_DOMAIN/messages", + headers: { + "Content-type": "application/json", + "Authorization": "Basic api:${MAILGUN_APIKEY}" + }, + data: json.encode(v: { + "from": "Username ", + "to": "email@example.com", + "subject": "InfluxDB critical alert", + "text": "There have been ${r._value} critical statuses." + }))} else {r with _value: 0})) +``` + +{{% /tab-content %}} + +{{< /tabs-wrapper >}} diff --git a/content/influxdb/v2.1/monitor-alert/templates/_index.md b/content/influxdb/v2.1/monitor-alert/templates/_index.md new file mode 100644 index 0000000000..f68665bf82 --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/templates/_index.md @@ -0,0 +1,14 @@ +--- +title: Monitor with templates +description: > + Use community templates to monitor data in many supported environments. Monitor infrastructure, networking, IoT, software, security, TICK stack, and more. +menu: + influxdb_2_1: + parent: Monitor & alert +weight: 104 +influxdb/v2.1/tags: [monitor, templates] +--- + +Use one of our community templates to quickly set up InfluxDB (with a bucket and dashboard) to collect, analyze, and monitor data in supported environments. + +{{< children >}} diff --git a/content/influxdb/v2.1/monitor-alert/templates/infrastructure/_index.md b/content/influxdb/v2.1/monitor-alert/templates/infrastructure/_index.md new file mode 100644 index 0000000000..08d4a009e6 --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/templates/infrastructure/_index.md @@ -0,0 +1,14 @@ +--- +title: Monitor infrastructure +description: > + Use one of our community templates to quickly set up InfluxDB (with a bucket and dashboard) to collect, analyze, and monitor your infrastructure. +menu: + influxdb_2_1: + parent: Monitor with templates +weight: 104 +influxdb/v2.1/tags: [monitor, templates, infrastructure] +--- + +Use one of our community templates to quickly set up InfluxDB (with a bucket and dashboard) to collect, analyze, and monitor your infrastructure. + +{{< children >}} diff --git a/content/influxdb/v2.1/monitor-alert/templates/infrastructure/aws.md b/content/influxdb/v2.1/monitor-alert/templates/infrastructure/aws.md new file mode 100644 index 0000000000..fd44320915 --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/templates/infrastructure/aws.md @@ -0,0 +1,57 @@ +--- +title: Monitor Amazon Web Services (AWS) +description: > + Use the AWS CloudWatch Monitoring template to monitor data from Amazon Web Services (AWS), Amazon Elastic Compute Cloud (EC2), and Amazon Elastic Load Balancing (ELB) with the AWS CloudWatch Service. +menu: + influxdb_2_1: + parent: Monitor infrastructure + name: AWS CloudWatch +weight: 201 +--- + +Use the [AWS CloudWatch Monitoring template](https://github.com/influxdata/community-templates/tree/master/aws_cloudwatch) to monitor data from [Amazon Web Services (AWS)](https://aws.amazon.com/), [Amazon Elastic Compute Cloud (EC2)](https://aws.amazon.com/ec2/), and [Amazon Elastic Load Balancing (ELB)](https://aws.amazon.com/elasticloadbalancing/) with the [AWS CloudWatch Service](https://aws.amazon.com/cloudwatch/). + +The AWS CloudWatch Monitoring template includes the following: + +- two [dashboards](/influxdb/v2.1/reference/glossary/#dashboard): + - **AWS CloudWatch NLB (Network Load Balancers) Monitoring**: Displays data from the `cloudwatch_aws_network_elb measurement` + - **AWS CloudWatch Instance Monitoring**: Displays data from the `cloudwatch_aws_ec2` measurement +- two [buckets](/influxdb/v2.1/reference/glossary/#bucket): `kubernetes` and `cloudwatch` +- two labels: `inputs.cloudwatch`, `AWS` +- one variable: `v.bucket` +- one [Telegraf configuration](/influxdb/v2.1/telegraf-configs/): [AWS CloudWatch input plugin](/{{< latest "telegraf" >}}/plugins//#cloudwatch) + +## Apply the template + +1. Use the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) to run the following command: + + ```sh + influx apply -f https://raw.githubusercontent.com/influxdata/community-templates/master/aws_cloudwatch/aws_cloudwatch.yml + ``` + For more information, see [influx apply](/influxdb/v2.1/reference/cli/influx/apply/). +2. [Install Telegraf](/{{< latest "telegraf" >}}/introduction/installation/) on a server with network access to both the CloudWatch API and [InfluxDB v2 API](/influxdb/v2.1/reference/api/). +3. In your Telegraf configuration file (`telegraf.conf`), find the following example `influxdb_v2` output plugins, and then **replace** the `urls` to specify the servers to monitor: + + ```sh + ## k8s + [[outputs.influxdb_v2]] + urls = ["http://influxdb.monitoring:8086"] + organization = "InfluxData" + bucket = "kubernetes" + token = "secret-token" + + ## cloudv2 sample + [[outputs.influxdb_v2]] + urls = ["$INFLUX_HOST"] + token = "$INFLUX_TOKEN" + organization = "$INFLUX_ORG" + bucket = “cloudwatch" + ``` +4. [Start Telegraf](/influxdb/v2.1/write-data/no-code/use-telegraf/auto-config/#start-telegraf). + +## View the incoming data + +1. In the InfluxDB user interface (UI), select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} +2. Open your AWS dashboards, and then set the `v.bucket` variable to specify the bucket to query data from (`kubernetes` or `cloudwatch`). diff --git a/content/influxdb/v2.1/monitor-alert/templates/infrastructure/docker.md b/content/influxdb/v2.1/monitor-alert/templates/infrastructure/docker.md new file mode 100644 index 0000000000..73ed2a8590 --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/templates/infrastructure/docker.md @@ -0,0 +1,54 @@ +--- +title: Monitor Docker +description: > + Use the [Docker Monitoring template](https://github.com/influxdata/community-templates/tree/master/docker) to monitor your Docker containers. +menu: + influxdb_2_1: + parent: Monitor infrastructure + name: Docker +weight: 202 +--- + +Use the [Docker Monitoring template](https://github.com/influxdata/community-templates/tree/master/docker) to monitor your Docker containers. First, [apply the template](#apply-the-template), and then [view incoming data](#view-incoming-data). +This template uses the [Docker input plugin](/{{< latest "telegraf" >}}/plugins//#docker) to collect metrics stored in InfluxDB and display these metrics in a dashboard. + +The Docker Monitoring template includes the following: + +- one [dashboard](/influxdb/v2.1/reference/glossary/#dashboard): **Docker** +- one [bucket](/influxdb/v2.1/reference/glossary/#bucket): `docker, 7d retention` +- labels: Docker input plugin labels +- one [Telegraf configuration](/influxdb/v2.1/telegraf-configs/): Docker input plugin +- one variable: `bucket` +- four [checks](/influxdb/v2.1/reference/glossary/#check): `Container cpu`, `mem`, `disk`, `non-zero exit` +- one [notification endpoint](/influxdb/v2.1/reference/glossary/#notification-endpoint): `Http Post` +- one [notification rule](/influxdb/v2.1/reference/glossary/#notification-rule): `Crit Alert` + +For more information about how checks, notification endpoints, and notifications rules work together, see [monitor data and send alerts](/influxdb/v2.1/monitor-alert/). + +## Apply the template + +1. Use the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) to run the following command: + + ```sh + influx apply -f https://raw.githubusercontent.com/influxdata/community-templates/master/docker/docker.yml + ``` + For more information, see [influx apply](/influxdb/v2.1/reference/cli/influx/apply/). + + > **Note:** Ensure your `influx` CLI is configured with your account credentials and that configuration is active. For more information, see [influx config](/influxdb/v2.1/reference/cli/influx/config/). + +2. [Install Telegraf](/{{< latest "telegraf" >}}/introduction/installation/) on a server with network access to both the Docker containers and [InfluxDB v2 API](/influxdb/v2.1/reference/api/). +3. In your [Telegraf configuration file (`telegraf.conf`)](/influxdb/v2.1/telegraf-configs/), do the following: + - Depending on how you run Docker, you may need to customize the [Docker input plugin](/{{< latest "telegraf" >}}/plugins//#docker) configuration, for example, you may need to specify the `endpoint` value. + - Set the following environment variables: + - INFLUX_TOKEN: Token must have permissions to read Telegraf configurations and write data to the `telegraf` bucket. See how to [view tokens](/influxdb/v2.1/security/tokens/view-tokens/). + - INFLUX_ORG: Name of your organization. See how to [view your organization](/influxdb/v2.1/organizations/view-orgs/). + - INFLUX_HOST: Your InfluxDB host URL, for example, localhost, a remote instance, or InfluxDB Cloud. + +4. [Start Telegraf](/influxdb/v2.1/write-data/no-code/use-telegraf/auto-config/#start-telegraf). + +## View incoming data + +1. In the InfluxDB user interface (UI), select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} +2. Open the **Docker** dashboard to start monitoring. diff --git a/content/influxdb/v2.1/monitor-alert/templates/infrastructure/vshpere.md b/content/influxdb/v2.1/monitor-alert/templates/infrastructure/vshpere.md new file mode 100644 index 0000000000..fbb19b1ba1 --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/templates/infrastructure/vshpere.md @@ -0,0 +1,55 @@ +--- +title: Monitor vSphere +description: > + Use the [vSphere Dashboard for InfluxDB v2 template](https://github.com/influxdata/community-templates/tree/master/vsphere) to monitor your vSphere host. +menu: + influxdb_2_1: + parent: Monitor infrastructure + name: vSphere +weight: 206 +--- + +Use the [vSphere Dashboard for InfluxDB v2 template](https://github.com/influxdata/community-templates/tree/master/vsphere) to monitor your vSphere host. First, [apply the template](#apply-the-template), and then [view incoming data](#view-incoming-data). +This template uses the [Docker input plugin](/{{< latest "telegraf" >}}/plugins//#docker) to collect metrics stored in InfluxDB and display these metrics in a dashboard. + +The Docker Monitoring template includes the following: + +- one [dashboard](/influxdb/v2.1/reference/glossary/#dashboard): **vsphere** +- one [bucket](/influxdb/v2.1/reference/glossary/#bucket): `vsphere` +- label: vsphere +- one [Telegraf configuration](/influxdb/v2.1/telegraf-configs/): InfluxDB v2 output plugin, vSphere input plugin +- one variable: `bucket` + +## Apply the template + +1. Use the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) to run the following command: + + ```sh + influx apply -f https://raw.githubusercontent.com/influxdata/community-templates/master/vsphere/vsphere.yml + ``` + For more information, see [influx apply](/influxdb/v2.1/reference/cli/influx/apply/). + + > **Note:** Ensure your `influx` CLI is configured with your account credentials and that configuration is active. For more information, see [influx config](/influxdb/v2.1/reference/cli/influx/config/). + +2. [Install Telegraf](/{{< latest "telegraf" >}}/introduction/installation/) on a server with network access to both the vSphere host and [InfluxDB v2 API](/influxdb/v2.1/reference/api/). +3. In your [Telegraf configuration file (`telegraf.conf`)](/influxdb/v2.1/telegraf-configs/), do the following: + - Set the following environment variables: + - INFLUX_TOKEN: Token must have permissions to read Telegraf configurations and write data to the `telegraf` bucket. See how to [view tokens](/influxdb/v2.1/security/tokens/view-tokens/). + - INFLUX_ORG: Name of your organization. See how to [view your organization](/influxdb/v2.1/organizations/view-orgs/). + - INFLUX_HOST: Your InfluxDB host URL, for example, localhost, a remote instance, or InfluxDB Cloud. + - INFLUX_BUCKET: Bucket to store data in. To use the bucket included, you must export the variable: `export INFLUX_BUCKET=vsphere` +4. - Set the host address to the vSphere and provide the `username` and `password` as variables: + ```sh + vcenters = [ "https://$VSPHERE_HOST/sdk" ] + username = "$vsphere-user" + password = "$vsphere-password" + ``` + +4. [Start Telegraf](/influxdb/v2.1/write-data/no-code/use-telegraf/auto-config/#start-telegraf). + +## View incoming data + +1. In the InfluxDB user interface (UI), select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} +2. Open the **vsphere** dashboard to start monitoring. diff --git a/content/influxdb/v2.1/monitor-alert/templates/infrastructure/windows.md b/content/influxdb/v2.1/monitor-alert/templates/infrastructure/windows.md new file mode 100644 index 0000000000..c516858a4f --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/templates/infrastructure/windows.md @@ -0,0 +1,52 @@ +--- +title: Monitor Windows +description: > + Use the [Windows System Monitoring template](https://github.com/influxdata/community-templates/tree/master/windows_system) to monitor your Windows system. +menu: + influxdb_2_1: + parent: Monitor infrastructure + name: Windows +weight: 207 +--- + +Use the [Windows System Monitoring template](https://github.com/influxdata/community-templates/tree/master/windows_system) to monitor your Windows system. First, [apply the template](#apply-the-template), and then [view incoming data](#view-incoming-data). + +The Windows System Monitoring template includes the following: + +- one [dashboard](/influxdb/v2.1/reference/glossary/#dashboard): **Windows System** +- one [bucket](/influxdb/v2.1/reference/glossary/#bucket): `telegraf`, 7d retention +- label: `Windows System Template`, Telegraf plugin labels: `outputs.influxdb_v2` +- one [Telegraf configuration](/influxdb/v2.1/telegraf-configs/): InfluxDB v2 output plugin, Windows Performance Counters input plugin +- two variables: `bucket`, `windows_host` + +## Apply the template + +1. Use the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) to run the following command: + + ```sh + influx apply -f https://raw.githubusercontent.com/influxdata/community-templates/master/windows_system/windows_system.yml + ``` + For more information, see [influx apply](/influxdb/v2.1/reference/cli/influx/apply/). + + > **Note:** Ensure your `influx` CLI is configured with your account credentials and that configuration is active. For more information, see [influx config](/influxdb/v2.1/reference/cli/influx/config/). + +2. [Install Telegraf](/{{< latest "telegraf" >}}/introduction/installation/) on a server with network access to both the Windows system and [InfluxDB v2 API](/influxdb/v2.1/reference/api/). +3. In your [Telegraf configuration file (`telegraf.conf`)](/influxdb/v2.1/telegraf-configs/), do the following: + - Set the following environment variables: + - INFLUX_TOKEN: Token must have permissions to read Telegraf configurations and write data to the `telegraf` bucket. See how to [view tokens](/influxdb/v2.1/security/tokens/view-tokens/). + - INFLUX_ORG: Name of your organization. See how to [view your organization](/influxdb/v2.1/organizations/view-orgs/). + - INFLUX_URL: Your InfluxDB host URL, for example, localhost, a remote instance, or InfluxDB Cloud. + +4. [Start Telegraf](/influxdb/v2.1/write-data/no-code/use-telegraf/auto-config/#start-telegraf). +5. To monitor multiple Windows systems, repeat steps 1-4 for each system. + +## View incoming data + +1. In the InfluxDB user interface (UI), select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} +2. Open the **Windows System** dashboard to start monitoring. + + {{% note %}} + If you're monitoring multiple Windows machines, switch between them using the `windows_host` filter at the top of the dashboard. + {{% /note %}} diff --git a/content/influxdb/v2.1/monitor-alert/templates/networks/_index.md b/content/influxdb/v2.1/monitor-alert/templates/networks/_index.md new file mode 100644 index 0000000000..24ef345cb6 --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/templates/networks/_index.md @@ -0,0 +1,14 @@ +--- +title: Monitor networks +description: > + Use one of our community templates to quickly set up InfluxDB (with a bucket and dashboard) to collect, analyze, and monitor your networks. +menu: + influxdb_2_1: + parent: Monitor with templates +weight: 104 +influxdb/v2.1/tags: [monitor, templates, networks, networking] +--- + +Use one of our community templates to quickly set up InfluxDB (with a bucket and dashboard) to collect, analyze, and monitor your networks. + +{{< children >}} \ No newline at end of file diff --git a/content/influxdb/v2.1/monitor-alert/templates/networks/haproxy.md b/content/influxdb/v2.1/monitor-alert/templates/networks/haproxy.md new file mode 100644 index 0000000000..1f90117004 --- /dev/null +++ b/content/influxdb/v2.1/monitor-alert/templates/networks/haproxy.md @@ -0,0 +1,48 @@ +--- +title: Monitor HAProxy +description: > + Use the [HAProxy for InfluxDB v2 template](https://github.com/influxdata/community-templates/tree/master/haproxy) to monitor your HAProxy instance. +menu: + influxdb_2_1: + parent: Monitor networks + name: HAproxy +weight: 201 +--- + +Use the [HAProxy for InfluxDB v2 template](https://github.com/influxdata/community-templates/tree/master/haproxy) to monitor your HAProxy instances. First, [apply the template](#apply-the-template), and then [view incoming data](#view-incoming-data). +This template uses the [HAProxy input plugin](/{{< latest "telegraf" >}}/plugins//#haproxy) to collect metrics stored in an HAProxy instance and display these metrics in a dashboard. + +The HAProxy for InfluxDB v2 template includes the following: + +- one [dashboard](/influxdb/v2.1/reference/glossary/#dashboard): **HAProxy** +- one [bucket](/influxdb/v2.1/reference/glossary/#bucket): `haproxy` +- label: `haproxy` +- one [Telegraf configuration](/influxdb/v2.1/telegraf-configs/): HAProxy input plugin, InfluxDB v2 output plugin +- one variable: `bucket` + +## Apply the template + +1. Use the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) to run the following command: + + ```sh + influx apply -f https://raw.githubusercontent.com/influxdata/community-templates/master/haproxy/haproxy.yml + ``` + For more information, see [influx apply](/influxdb/v2.1/reference/cli/influx/apply/). + + > **Note:** Ensure your `influx` CLI is configured with your account credentials and that configuration is active. For more information, see [influx config](/influxdb/v2.1/reference/cli/influx/config/). + +2. [Install Telegraf](/{{< latest "telegraf" >}}/introduction/installation/) on a server with network access to both the HAProxy instances and [InfluxDB v2 API](/influxdb/v2.1/reference/api/). +3. In your [Telegraf configuration file (`telegraf.conf`)](/influxdb/v2.1/telegraf-configs/), do the following: + - Set the following environment variables: + - INFLUX_TOKEN: Token must have permissions to read Telegraf configurations and write data to the `haproxy` bucket. See how to [view tokens](/influxdb/v2.1/security/tokens/view-tokens/). + - INFLUX_ORG: Name of your organization. See how to [view your organization](/influxdb/v2.1/organizations/view-orgs/). + - INFLUX_HOST: Your InfluxDB host URL, for example, localhost, a remote instance, or InfluxDB Cloud. + +4. [Start Telegraf](/influxdb/v2.1/write-data/no-code/use-telegraf/auto-config/#start-telegraf). + +## View incoming data + +1. In the InfluxDB user interface (UI), select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} +2. Open the **HAProxy** dashboard to start monitoring. diff --git a/content/influxdb/v2.1/notebooks/_index.md b/content/influxdb/v2.1/notebooks/_index.md new file mode 100644 index 0000000000..2fe9c65968 --- /dev/null +++ b/content/influxdb/v2.1/notebooks/_index.md @@ -0,0 +1,17 @@ +--- +title: Notebooks +seotitle: Build notebooks in InfluxDB Cloud +description: > + Use notebooks to build and annotate processes and data flows for time series data. +menu: + influxdb_2_1: + name: Notebooks +weight: 6 +influxdb/v2.1/tags: [notebooks] +--- + +Notebooks are a way to build and annotate processes and data flows for time series data. Notebooks include cells and controls to transform the data in your bucket and other countless possibilities. + +To learn how to use notebooks, check out the following articles: + +{{< children >}} diff --git a/content/influxdb/v2.1/notebooks/clean-data.md b/content/influxdb/v2.1/notebooks/clean-data.md new file mode 100644 index 0000000000..93ebd7e208 --- /dev/null +++ b/content/influxdb/v2.1/notebooks/clean-data.md @@ -0,0 +1,40 @@ +--- +title: Normalize data with notebooks +description: > + Clean, standardize, or normalize you data to make it easier to compare with other measurements. +weight: 105 +influxdb/v2.1/tags: [notebooks] +menu: + influxdb_2_1: + name: Normalize data with notebooks + parent: Notebooks +--- + +Learn how to create a notebook that normalizes data. Walk through the following example to create a notebook that does the following: + +- Inputs sample data from NOAA +- Normalizes sample data with a Flux script +- Outputs normalized data to a bucket + +## Requirements +- This example uses [NOAA water database data](/influxdb/v2.0/reference/sample-data/#noaa-water-sample-data). Note that using this data counts towards your total usage. +- Create a destination bucket to write normalized data to. For details, see [Create a bucket](/influxdb/v2.1/organizations/buckets/create-bucket/). + +## Normalize data with a notebook +1. Create a new notebook (see [Create a notebook](/influxdb/v2.1/notebooks/create-notebook/)). +2. Add a **Metric Selector** cell to select a bucket to query data from: + - In the **Choose a bucket** dropdown, select your NOAA bucket. + - Select the **h2o_temperature** field. + - Select the **mean** function from the aggregate selector in the upper-right. +3. Add a **Flux Transformation** cell with the following script to bring in data from the previous cell and normalize it: + ```sh + __PREVIOUS_RESULT__ + |> map(fn: (r) => ({ r with _value: float(v: r._value) / 10.0 })) + ``` +4. Add an **Output to Bucket** cell: + - Select the destination bucket for your normalized data. +5. Add a **Markdown** cell to add a note to your team about what this notebook does. For example, the cell might say, "This notebook makes `h20_temperature` easier to view alongside `water_level`." +5. Click **Preview** in the upper left to verify that your notebook runs and preview the output. +6. Run your notebook: + - Click **Run** to run the notebook and write to the output bucket a single time. + - To write continuously, click **Export as Task** in the upper right corner of the **Output to Bucket** cell. For details about working with tasks, see [Manage tasks](/influxdb/v2.1/process-data/manage-tasks/). diff --git a/content/influxdb/v2.1/notebooks/create-notebook.md b/content/influxdb/v2.1/notebooks/create-notebook.md new file mode 100644 index 0000000000..cc20514a74 --- /dev/null +++ b/content/influxdb/v2.1/notebooks/create-notebook.md @@ -0,0 +1,109 @@ +--- +title: Create a notebook +description: > + Create a notebook to explore, visualize, and process your data. +weight: 102 +influxdb/v2.1/tags: [notebooks] +menu: + influxdb_2_1: + name: Create a notebook + parent: Notebooks +--- +To learn how notebooks can be useful and to see an overview of different cell types available in notebooks, see [Overview of Notebooks](/influxdb/v2.1/notebooks/overview/). + +1. In the navigation menu on the left, click **Notebooks**. + + {{< nav-icon "notebooks" >}} +2. Click one of the following options under **Create a Notebook**: + - New Notebook + - Set an Alert + - Schedule a Task + - Write a Flux Script +3. Enter a name for your notebook in the **Untitled Notebook** field. +3. Do the following at the top of the page: + - Select your local time zone or UTC. + - Choose a time range for your data. +4. Consider which notebook cells to add to your notebook. You need to have one input cell for other cells to run properly. The default notebook cell types included in your notebook (**Data Source**, **Visualization**, and **Action**) vary depending on the type of notebook you selected in step 2. +5. Select your bucket in your query or Flux script, and then select the filters to narrow your data. +6. Do one of the following: + - To view results in your cells (for example, to view your **Visualization** or **Action**) *without writing data*, click **Preview** (or press **CTRL + Enter**). + - To view the results of each cell and write the results to the specified output bucket, click **Run**. +7. (Optional) Change your visualization settings with the dropdown menus and gear icon at the top of the **Visualization** cell. +8. (Optional) Click the **+** icon, and then add one or more of the following cell types to your notebook: + + - [Data source](#add-a-data-source-cell): to pull information into your notebook + - [Visualization](#add-a-visualization-cell): to + - [Action](#add-an-action-cell): filter and apply changes to your data, for example, create an alert, process data with a task, or output data to a bucket +9. (Optional) [Convert a cell into raw Flux script](#view-and-edit-flux-script-in-a-cell) to view and edit the code. + +### Add a data source cell + +1. Select **Flux Script** or **Query Builder** as your input, and then select or enter the bucket to pull data from. +2. Select filters to narrow your data. +3. Select **Preview** (**CTRL + Enter**) or **Run** in the upper left dropdown menu. + +### Add an action cell + +1. Select one of the following action cell-types: + - **Alert** + - **Downsample**: Window data by time and apply an aggregate to each window to downsample data. For more information, see [Downsample data with notebooks](/influxdb/v2.1/notebooks/downsample/). +2. Select **Preview** (**CTRL + Enter**) or **Run** in the upper left dropdown menu. + +{{% warn %}} +If your cell contains a custom script that uses any output function to write data to InfluxDB (for example: the `to()` function) or sends data to a third-party service, clicking Preview will write data. +{{% /warn %}} + +### Add a visualization cell + +Select one of the following visualization cell-types: + +- Table +- Graph +- Note +For detail on available visualization types and how to use them, see [Visualization types](/influxdb/cloud/visualize-data/visualization-types/). + +#### Visualization + +- To change your visualization type, select a new type from the dropdown menu at the top of the cell. +- (For histogram only) To specify values, click **Select**. +- To configure the visualization, click **Configure**. +- To download results as an annotated CSV file, click the **CSV** button. +- To export to the dashboard, click **Export to Dashboard**. + +### Add an action cell + +Select one of the following action cell-types: + +- To recieve a notification, select [Alert](#alert) and complete the steps below. +- To write output to a bucket, select [Output to Bucket](#output-to-bucket) and complete the steps below. +- To create a task, select [Task](#task) and complete the steps below. + +#### Alert + +1. Enter a time range to automatically check the data and enter your query offset. +2. Customize the conditions to send an alert. +3. Select an endpoint to receive an alert: + - Slack and a Slack Channel + - HTTP post + - Pager Duty +4. (Optional) Personalize your message. By default, the message is "${strings.title(v: r._type)} for ${r._source_measurement} triggered at ${time(v: r._source_timestamp)}!" +5. Click **Export as Task** to create your alert. + +#### Output to bucket + +1. Select a bucket. +2. Click **Preview** to see what would be written to the bucket without commiting, or click **Run** in the upper left to write, or select **Export as Task** to schedule your output as a task. + +#### Task + +1. Enter a time and an offset to schedule the task. +2. Click **Export as Task** to save. + +### View and edit Flux script in a cell +Convert your notebook cells into raw Flux script to view and edit the code. Conversion to Flux is available for the following cell types: + - **Inputs: Metric Selector** + - **Transform: Column Editor** and **Downsample** + +1. Click the overflow menu icon in the cell you want to view as Flux, and then select **Convert to |> Flux**. You won't be able to undo this step. + A Flux cell appears with underlying script for the selected cell. +3. View and edit the Flux script as needed. diff --git a/content/influxdb/v2.1/notebooks/manage-notebooks.md b/content/influxdb/v2.1/notebooks/manage-notebooks.md new file mode 100644 index 0000000000..5b00569b21 --- /dev/null +++ b/content/influxdb/v2.1/notebooks/manage-notebooks.md @@ -0,0 +1,29 @@ +--- +title: Manage notebooks +description: View, update, and delete notebooks. +weight: 103 +influxdb/v2.1/tags: [notebooks] +menu: + influxdb_2_1: + name: Manage notebooks + parent: Notebooks +--- + +View, update, and delete notebooks in the UI. + +## View or update notebooks +1. In the navigation menu on the left, click **Notebooks**. + + {{< nav-icon "notebooks" >}} + + A list of notebooks appears. +2. Click a notebook to open it. +3. To update, edit the notebook's cells and content. Changes are saved automatically. + +## Delete a notebook +1. In the navigation menu on the left, click **Notebooks**. + + {{< nav-icon "notebooks" >}} +2. Hover over a notebook in the list that appears. +3. Click **Delete Notebook**. +4. Click **Confirm**. diff --git a/content/influxdb/v2.1/notebooks/overview.md b/content/influxdb/v2.1/notebooks/overview.md new file mode 100644 index 0000000000..b7dd1d2f2e --- /dev/null +++ b/content/influxdb/v2.1/notebooks/overview.md @@ -0,0 +1,81 @@ +--- +title: Overview of notebooks +description: > + Learn about the building blocks of a notebook. +weight: 101 +influxdb/v2.1/tags: [notebooks] +menu: + influxdb_2_1: + name: Overview of notebooks + parent: Notebooks +--- + +Learn about the building blocks of a notebook, how notebooks can help show how data is processed, and discover some common use cases. + +To use different notebook cell types, controls, and uses to process data, see: +- [Notebook concepts](/influxdb/v2.1/notebooks/overview/#notebook-concepts) +- [Notebook controls](/influxdb/v2.1/notebooks/overview/#notebook-controls) +- [Notebook cell types](/influxdb/v2.1/notebooks/overview/#notebook-cell-types) + +## Notebook concepts + +Using notebooks, you can: + +- Create documents with live code, equations, visualizations, and explanatory notes. +- Create dashboard cells or scheduled tasks. +- Clean and downsample data. +- Build runbooks. +- Document data processing steps. + +## Notebook controls + +The following options appear at the top of each notebook. + +### Preview/Run mode + +- Select **Preview** (or press **Control+Enter**) to display results of each cell without writing data. Helps to verify that cells return expected results before writing data. +- Select **Run** mode displays results of each cell and writes data to the selected bucket. + +### Presentation mode + +Display notebooks in full screen with Presentation mode, hiding the left and top navigation menus so only the cells appear. This mode might be helpful, for example, for stationary screens dedicated to monitoring visualizations. + +### Local or UTC timezone + +Click the timezone dropdown list to select a timezone to use for the dashboard. Select either the local time (default) or UTC. + +### Time range + +Select from the options in the dropdown list or select **Custom Time Range** to enter a custom time range with precision up to nanoseconds. + +## Notebook cell types + +The following cell types are available for your notebook: +- [Data source](#data-source) +- [Visualization](#visualization) +- [Actions](#actions) + +### Data source + +At least one input cell is required in a notebook for other cells to run. + +- **Flux Script**: Input your data using a Flux script. +- **Query Builder**: Input your data using a query. + +### Visualization + +- **Table**: View your data in a table. +- **Graph**: View your data in a graph. +- **Note**: Create explanatory notes or other information for yourself or one of your team members. + +### Action + +- **Column Editor**: Modify column visibility and naming. +- **Markdown**: Create explanatory notes or other information for yourself or one of your team members. +- **Visualization**: Represents your data in visual formats such as graphs or charts. + +### Output + +- **Alert**: Set up alerts. See how to [monitor data and send alerts](https://docs.influxdata.com/influxdb/v2.0/monitor-alert/). +- **Tasks**: Set up tasks. See how to [manage tasks in InfluxDB] (https://docs.influxdata.com/influxdb/v2.0/process-data/manage-tasks/). +- **Output to Bucket**: In **Preview** mode, this cell represents what would be written if the data was going to be committed to a bucket. In **Run** mode, this writes data to the specified bucket. diff --git a/content/influxdb/v2.1/notebooks/troubleshoot-notebooks.md b/content/influxdb/v2.1/notebooks/troubleshoot-notebooks.md new file mode 100644 index 0000000000..ffb281ee0d --- /dev/null +++ b/content/influxdb/v2.1/notebooks/troubleshoot-notebooks.md @@ -0,0 +1,19 @@ +--- +title: Troubleshoot notebooks +description: Common issues with the notebooks feature. +weight: 106 +influxdb/v2.1/tags: [notebooks] +menu: + influxdb_2_1: + name: Troubleshoot notebooks + parent: Notebooks +--- + +### No measurements appear in my bucket even though there's data in it. +Try changing the time range. You might have measurements prior to the time range you selected. For example, if the selected time range is `Past 1h` and the last write happened 16 hours ago, you'd need to change the time range to `Past 24h` (or more) to see your data. + +### "No bucket exists" error message appears. +This error appears when the Buckets API endpoint returns a list of bucket and you don’t have access to that bucket. Verify that you have access permissions to the bucket that you're trying to query or write to. + +### Metric selector crashes. +This can occur with high-cardinality buckets when there's too much data for the browser. To decrease the amount of data in your bucket, see how to [resolve high series cardinality](/influxdb/v2.1/write-data/best-practices/resolve-high-cardinality/). diff --git a/content/influxdb/v2.1/organizations/_index.md b/content/influxdb/v2.1/organizations/_index.md new file mode 100644 index 0000000000..0c716ae7a9 --- /dev/null +++ b/content/influxdb/v2.1/organizations/_index.md @@ -0,0 +1,17 @@ +--- +title: Manage organizations +seotitle: Manage organizations in InfluxDB +description: Manage organizations in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_2_1: + name: Manage organizations +weight: 10 +influxdb/v2.1/tags: [organizations] +--- + +An **organization** is a workspace for a group of users. +All dashboards, tasks, buckets, members, etc., belong to an organization. + +The following articles provide information about managing organizations: + +{{< children >}} diff --git a/content/influxdb/v2.1/organizations/buckets/_index.md b/content/influxdb/v2.1/organizations/buckets/_index.md new file mode 100644 index 0000000000..4a8af0c8dd --- /dev/null +++ b/content/influxdb/v2.1/organizations/buckets/_index.md @@ -0,0 +1,20 @@ +--- +title: Manage buckets +seotitle: Manage buckets in InfluxDB +description: Manage buckets in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_2_1: + name: Manage buckets + parent: Manage organizations +weight: 105 +influxdb/v2.1/tags: [buckets] +--- + +A **bucket** is a named location where time series data is stored. +All buckets have a **retention period**, a duration of time that each data point persists. +InfluxDB drops all points with timestamps older than the bucket's retention period. +A bucket belongs to an organization. + +The following articles provide information about managing buckets: + +{{< children >}} diff --git a/content/influxdb/v2.1/organizations/buckets/create-bucket.md b/content/influxdb/v2.1/organizations/buckets/create-bucket.md new file mode 100644 index 0000000000..85b1173ae2 --- /dev/null +++ b/content/influxdb/v2.1/organizations/buckets/create-bucket.md @@ -0,0 +1,108 @@ +--- +title: Create a bucket +seotitle: Create a bucket in InfluxDB +description: Create buckets to store time series data in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_2_1: + name: Create a bucket + parent: Manage buckets +weight: 201 +--- + +Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) +to create a bucket. + +{{% note %}} +#### Bucket limits +A single InfluxDB {{< current-version >}} OSS instance supports approximately 20 buckets actively being +written to or queried across all organizations depending on the use case. +Any more than that can adversely affect performance. +{{% /note %}} + +## Create a bucket in the InfluxDB UI + +There are two places you can create a bucket in the UI. + +### Create a bucket from the Load Data menu + +1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. + + {{< nav-icon "data" >}} + +2. Click **{{< icon "plus" >}} Create Bucket** in the upper right. +3. Enter a **Name** for the bucket. +4. Select when to **Delete Data**: + - **Never** to retain data forever. + - **Older than** to choose a specific retention period. +5. Click **Create** to create the bucket. + +### Create a bucket in the Data Explorer + +1. In the navigation menu on the left, select **Explore* (**Data Explorer**). + + {{< nav-icon "data-explorer" >}} + +2. In the **From** panel in the Flux Builder, select `+ Create Bucket`. +3. Enter a **Name** for the bucket. +4. Select when to **Delete Data**: + - **Never** to retain data forever. + - **Older than** to choose a specific retention period. +5. Click **Create** to create the bucket. + +## Create a bucket using the influx CLI + +Use the [`influx bucket create` command](/influxdb/v2.1/reference/cli/influx/bucket/create) +to create a new bucket. A bucket requires the following: + +- bucket name +- organization name or ID +- retention period (duration to keep data) in one of the following units: + - nanoseconds (`ns`) + - microseconds (`us` or `µs`) + - milliseconds (`ms`) + - seconds (`s`) + - minutes (`m`) + - hours (`h`) + - days (`d`) + - weeks (`w`) + +```sh +# Syntax +influx bucket create -n -o -r + +# Example +influx bucket create -n my-bucket -o my-org -r 72h +``` + +## Create a bucket using the InfluxDB API + +Use the InfluxDB API to create a bucket. + +{{% note %}} +#### Bucket limits +A single InfluxDB {{< current-version >}} OSS instance supports approximately 20 buckets actively being +written to or queried across all organizations depending on the use case. +Any more than that can adversely affect performance. +{{% /note %}} + +Create a bucket in InfluxDB using an HTTP request to the InfluxDB API `/buckets` endpoint. +Use the `POST` request method and include the following in your request: + +| Requirement | Include by | +|:----------- |:---------- | +| Organization | Use `orgID` in the JSON payload. | +| Bucket | Use `name` in the JSON payload. | +| Retention Rules | Use `retentionRules` in the JSON payload. | +| API token | Use the `Authorization: Token` header. | + +#### Example + +The URL depends on the version and location of your InfluxDB {{< current-version >}} +instance _(see [InfluxDB URLs](/influxdb/v2.1/reference/urls/))_. + +```sh +{{% get-shared-text "api/v2.0/buckets/oss/create.sh" %}} +``` + +_For information about **InfluxDB API options and response codes**, see +[InfluxDB API Buckets documentation](/influxdb/v2.1/api/#operation/PostBuckets)._ diff --git a/content/influxdb/v2.1/organizations/buckets/delete-bucket.md b/content/influxdb/v2.1/organizations/buckets/delete-bucket.md new file mode 100644 index 0000000000..6924c5958a --- /dev/null +++ b/content/influxdb/v2.1/organizations/buckets/delete-bucket.md @@ -0,0 +1,56 @@ +--- +title: Delete a bucket +seotitle: Delete a bucket from InfluxDB +description: Delete a bucket from InfluxDB using the InfluxDB UI or the influx CLI +menu: + influxdb_2_1: + name: Delete a bucket + parent: Manage buckets +weight: 203 +--- + +Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) +to delete a bucket. + +## Delete a bucket in the InfluxDB UI + +1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. + + {{< nav-icon "data" >}} + +2. Hover over the bucket you would like to delete. +3. Click **{{< icon "delete" >}} Delete Bucket** and **Confirm** to delete the bucket. + +## Delete a bucket using the influx CLI + +Use the [`influx bucket delete` command](/influxdb/v2.1/reference/cli/influx/bucket/delete) +to delete a bucket a bucket by name or ID. + +### Delete a bucket by name +**To delete a bucket by name, you need:** + +- Bucket name +- Bucket's organization name or ID + + +```sh +# Syntax +influx bucket delete -n -o + +# Example +influx bucket delete -n my-bucket -o my-org +``` + +### Delete a bucket by ID +**To delete a bucket by ID, you need:** + +- Bucket ID _(provided in the output of `influx bucket list`)_ + + +```sh +# Syntax +influx bucket delete -i + +# Example +influx bucket delete -i 034ad714fdd6f000 +``` diff --git a/content/influxdb/v2.1/organizations/buckets/update-bucket.md b/content/influxdb/v2.1/organizations/buckets/update-bucket.md new file mode 100644 index 0000000000..7839bf8d82 --- /dev/null +++ b/content/influxdb/v2.1/organizations/buckets/update-bucket.md @@ -0,0 +1,75 @@ +--- +title: Update a bucket +seotitle: Update a bucket in InfluxDB +description: Update a bucket's name or retention period in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_2_1: + name: Update a bucket + parent: Manage buckets +weight: 202 +--- + +Use the `influx` command line interface (CLI) or the InfluxDB user interface (UI) to update a bucket. + +Note that updating an bucket's name will affect any assets that reference the bucket by name, including the following: + + - Queries + - Dashboards + - Tasks + - Telegraf configurations + - Templates + +If you change a bucket name, be sure to update the bucket in the above places as well. + +## Update a bucket's name in the InfluxDB UI + +1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. + + {{< nav-icon "data" >}} + +2. Click **Settings** under the bucket you want to rename. +3. Click **Rename**. +3. Review the information in the window that appears and click **I understand, let's rename my bucket**. +4. Update the bucket's name and click **Change Bucket Name**. + +## Update a bucket's retention period in the InfluxDB UI + +1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. + + {{< nav-icon "data" >}} + +2. Click **Settings** next to the bucket you want to update. +3. In the window that appears, edit the bucket's retention period. +4. Click **Save Changes**. + +## Update a bucket using the influx CLI + +Use the [`influx bucket update` command](/influxdb/v2.1/reference/cli/influx/bucket/update) +to update a bucket. Updating a bucket requires the following: + +- The bucket ID _(provided in the output of `influx bucket list`)_ +- The name or ID of the organization the bucket belongs to. + +{{< cli/influx-creds-note >}} + +##### Update the name of a bucket + +```sh +# Syntax +influx bucket update -i -n + +# Example +influx bucket update -i 034ad714fdd6f000 -n my-new-bucket +``` + +##### Update a bucket's retention period + +Valid retention period duration units are nanoseconds (`ns`), microseconds (`us` or `µs`), milliseconds (`ms`), seconds (`s`), minutes (`m`), hours (`h`), days (`d`), or weeks (`w`). + +```sh +# Syntax +influx bucket update -i -r + +# Example +influx bucket update -i 034ad714fdd6f000 -r 1209600000000000ns +``` diff --git a/content/influxdb/v2.1/organizations/buckets/view-buckets.md b/content/influxdb/v2.1/organizations/buckets/view-buckets.md new file mode 100644 index 0000000000..46f5de4507 --- /dev/null +++ b/content/influxdb/v2.1/organizations/buckets/view-buckets.md @@ -0,0 +1,34 @@ +--- +title: View buckets +seotitle: View buckets in InfluxDB +description: View a list of all the buckets for an organization in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_2_1: + name: View buckets + parent: Manage buckets +weight: 202 +--- + +## View buckets in the InfluxDB UI + +1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. + + {{< nav-icon "data" >}} + + A list of buckets with their retention policies and IDs appears. + +2. Click a bucket to open it in the **Data Explorer**. +3. Click the **bucket ID** to copy it to the clipboard. + +## View buckets using the influx CLI + +Use the [`influx bucket list` command](/influxdb/v2.1/reference/cli/influx/bucket/list) +to view a buckets in an organization. + +```sh +influx bucket list +``` + +Other filtering options such as filtering by organization, name, or ID are available. +See the [`influx bucket list` documentation](/influxdb/v2.1/reference/cli/influx/bucket/list) +for information about other available flags. diff --git a/content/influxdb/v2.1/organizations/create-org.md b/content/influxdb/v2.1/organizations/create-org.md new file mode 100644 index 0000000000..b396c1c9dc --- /dev/null +++ b/content/influxdb/v2.1/organizations/create-org.md @@ -0,0 +1,47 @@ +--- +title: Create an organization +seotitle: Create an organization in InfluxDB +description: Create an organization in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_2_1: + name: Create an organization + parent: Manage organizations +weight: 101 +products: [oss] +--- + +Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) +to create an organization. + +{{% note %}} +#### Organization and bucket limits +A single InfluxDB {{< current-version >}} OSS instance supports approximately 20 buckets actively being +written to or queried across all organizations depending on the use case. +Any more than that can adversely affect performance. +Because each organization is created with a bucket, we do not recommend more than +20 organizations in a single InfluxDB OSS instance. +{{% /note %}} + +## Create an organization in the InfluxDB UI + +1. In the navigation menu on the left, click the **Account dropdown**. + + {{< nav-icon "account" >}} + +2. Select **Create Organization**. +3. In the window that appears, enter an **Organization Name** and **Bucket Name** and click **Create**. + +## Create an organization using the influx CLI + +Use the [`influx org create` command](/influxdb/v2.1/reference/cli/influx/org/create) +to create a new organization. A new organization requires the following: + +- A name for the organization + +```sh +# Syntax +influx org create -n + +# Example +influx org create -n my-org +``` diff --git a/content/influxdb/v2.1/organizations/delete-org.md b/content/influxdb/v2.1/organizations/delete-org.md new file mode 100644 index 0000000000..ef9f6305c6 --- /dev/null +++ b/content/influxdb/v2.1/organizations/delete-org.md @@ -0,0 +1,41 @@ +--- +title: Delete an organization +seotitle: Delete an organization from InfluxDB +description: Delete an existing organization from InfluxDB using the influx CLI. +menu: + influxdb_2_1: + name: Delete an organization + parent: Manage organizations +weight: 104 +products: [oss] +--- + +Use the `influx` command line interface (CLI) +to delete an organization. + + + +## Delete an organization using the influx CLI + +Use the [`influx org delete` command](/influxdb/v2.1/reference/cli/influx/org/delete) +to delete an organization. Deleting an organization requires the following: + +- The organization ID _(provided in the output of `influx org list`)_ + +```sh +# Syntax +influx org delete -i + +# Example +influx org delete -i 034ad714fdd6f000 +``` diff --git a/content/influxdb/v2.1/organizations/members/_index.md b/content/influxdb/v2.1/organizations/members/_index.md new file mode 100644 index 0000000000..b877c913c4 --- /dev/null +++ b/content/influxdb/v2.1/organizations/members/_index.md @@ -0,0 +1,16 @@ +--- +title: Manage organization members +seotitle: Manage members of an organization in InfluxDB +description: Manage members of an organization in InfluxDB using the InfluxDB UI or CLI. +menu: + influxdb_2_1: + name: Manage members + parent: Manage organizations +weight: 106 +influxdb/v2.1/tags: [members] +--- + +A **member** is a user that belongs to an organization. +The following articles provide information about managing users: + +{{< children >}} diff --git a/content/influxdb/v2.1/organizations/members/add-member.md b/content/influxdb/v2.1/organizations/members/add-member.md new file mode 100644 index 0000000000..35cde655a9 --- /dev/null +++ b/content/influxdb/v2.1/organizations/members/add-member.md @@ -0,0 +1,36 @@ +--- +title: Add a member +seotitle: Add a member to an organization in InfluxDB +description: Add a member to an organization. +menu: + influxdb_2_1: + name: Add a member + parent: Manage members +weight: 201 +--- + +Use the `influx` command line interface (CLI) to add a member to an organization. + + + +## Add a member to an organization using the influx CLI + +1. Get a list of users and their IDs by running the following: + +```sh +influx user list +``` + +2. To add a user to an organization, run the following command: + +```sh +influx org members add -n -m +``` + +For more information, see the [`influx org members add` command](/influxdb/v2.1/reference/cli/influx/org/members/add). diff --git a/content/influxdb/v2.1/organizations/members/remove-member.md b/content/influxdb/v2.1/organizations/members/remove-member.md new file mode 100644 index 0000000000..c3fc4d4f97 --- /dev/null +++ b/content/influxdb/v2.1/organizations/members/remove-member.md @@ -0,0 +1,44 @@ +--- +title: Remove a member +seotitle: Remove a member from an organization in InfluxDB +description: Remove a member from an organization. +menu: + influxdb_2_1: + name: Remove a member + parent: Manage members +weight: 203 +--- + +Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) +to remove a member from an organization. + +{{% note %}} +Removing a member from an organization removes all permissions associated with the organization, +but it does not delete the user from the system entirely. +For information about deleting a user from InfluxDB, see [Delete a user](/influxdb/v2.1/users/delete-user/). +{{% /note %}} + +## Remove a member from an organization in the InfluxDB UI + +1. In the navigation menu on the left, select **Org (Organization)** > **Members**. + + {{< nav-icon "org" >}} + +2. Hover over the member you would like to delete and click the **{{< icon "delete" >}}** icon. +3. Click **Delete**. + +## Remove a member from an organization using the influx CLI + +Use the [`influx org members remove` command](/influxdb/v2.1/reference/cli/influx/org/members/remove) +to remove a member from an organization. Removing a member requires the following: + +- The organization name or ID _(provided in the output of [`influx org list`](/influxdb/v2.1/reference/cli/influx/org/list/))_ +- The member ID _(provided in the output of [`influx org members list`](/influxdb/v2.1/reference/cli/influx/org/members/list/))_ + +```sh +# Syntax +influx org members remove -o -i + +# Example +influx org members remove -o 00xXx0x00xXX0000 -i x0xXXXx00x0x000X +``` diff --git a/content/influxdb/v2.1/organizations/members/view-members.md b/content/influxdb/v2.1/organizations/members/view-members.md new file mode 100644 index 0000000000..3eb87a6601 --- /dev/null +++ b/content/influxdb/v2.1/organizations/members/view-members.md @@ -0,0 +1,35 @@ +--- +title: View members +seotitle: View members of an organization in InfluxDB +description: Review a list of members for an organization. +menu: + influxdb_2_1: + name: View members + parent: Manage members +weight: 202 +--- + +Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) +to view members of an organization. + +## View members of organization in the InfluxDB UI + +In the navigation menu on the left, select **Org (Organization)** > **Members**. + +{{< nav-icon "org" >}} + + +## View members of organization using the influx CLI + +Use the [`influx org members list` command](/influxdb/v2.1/reference/cli/influx/org/members/list) +to list members of an organization. Listing an organization's members requires the following: + +- The name or ID of the organization + +```sh +# Syntax +influx org members list -n + +# Example +influx org members list -n my-org +``` diff --git a/content/influxdb/v2.1/organizations/switch-org.md b/content/influxdb/v2.1/organizations/switch-org.md new file mode 100644 index 0000000000..213b5acae4 --- /dev/null +++ b/content/influxdb/v2.1/organizations/switch-org.md @@ -0,0 +1,22 @@ +--- +title: Switch organizations +seotitle: Switch organizations in InfluxDB +description: Switch from one organization to another in the InfluxDB UI +menu: + influxdb_2_1: + name: Switch organizations + parent: Manage organizations +weight: 105 +products: [oss] +--- + +Use the InfluxDB user interface (UI) to switch from one organization to another. The organization you're currently viewing determines what dashboards, tasks, buckets, members, and other assets you can access. + +## Switch organizations in the InfluxDB UI + +1. In the navigation menu on the left, click the **Account dropdown**. + + {{< nav-icon "account" >}} + +2. Select **Switch Organizations**. +3. Click the organization you want to switch to. diff --git a/content/influxdb/v2.1/organizations/update-org.md b/content/influxdb/v2.1/organizations/update-org.md new file mode 100644 index 0000000000..662ab0f5cd --- /dev/null +++ b/content/influxdb/v2.1/organizations/update-org.md @@ -0,0 +1,49 @@ +--- +title: Update an organization +seotitle: Update an organization in InfluxDB +description: Update an organization's name and assets in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_2_1: + name: Update an organization + parent: Manage organizations +weight: 103 +--- + +Use the `influx` command line interface (CLI) or the InfluxDB user interface (UI) to update an organization. + +Note that updating an organization's name will affect any assets that reference the organization by name, including the following: + + - Queries + - Dashboards + - Tasks + - Telegraf configurations + - Templates + +If you change an organization name, be sure to update the organization in the above places as well. + +## Update an organization in the InfluxDB UI + +1. In the navigation menu on the left, click the user icon > **About**. + + {{< img-hd src="/img/influxdb/user-icon.png" alt="User Icon" />}} + +2. Click **{{< icon "edit" >}} Rename**. A verification window appears. +3. Review the information, and then click **I understand, let's rename my organization**. +4. Enter a new name for your organization, and then click **Change organization name**. + +## Update an organization using the influx CLI + +Use the [`influx org update` command](/influxdb/v2.1/reference/cli/influx/org/update) +to update an organization. Updating an organization requires the following: + +- The org ID _(provided in the output of `influx org list`)_ + +##### Update the name of a organization + +```sh +# Syntax +influx org update -i -n + +# Example +influx org update -i 034ad714fdd6f000 -n my-new-org +``` diff --git a/content/influxdb/v2.1/organizations/view-orgs.md b/content/influxdb/v2.1/organizations/view-orgs.md new file mode 100644 index 0000000000..145accf5b2 --- /dev/null +++ b/content/influxdb/v2.1/organizations/view-orgs.md @@ -0,0 +1,58 @@ +--- +title: View organizations +seotitle: View organizations in InfluxDB +description: Review a list of organizations in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_2_1: + name: View organizations + parent: Manage organizations +weight: 102 +--- + +Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) +to view organizations. + +## View organizations in the InfluxDB UI + +1. In the navigation menu on the left, click the **Account dropdown**. + + {{< nav-icon "account" >}} + +2. Select **Switch Organizations**. The list of organizations appears. + +## View organizations using the influx CLI + +Use the [`influx org list` command](/influxdb/v2.1/reference/cli/influx/org/list) +to view organizations. + +```sh +influx org list +``` + +Filtering options such as filtering by name or ID are available. +See the [`influx org list` documentation](/influxdb/v2.1/reference/cli/influx/org/list) +for information about other available flags. + +## View your organization ID + +Use the InfluxDB UI or `influx` CLI to view your organization ID. + +### Organization ID in the UI + +After logging in to the InfluxDB UI, your organization ID appears in the URL. + +

    +http://localhost:8086/orgs/03a2bbf46249a000/...
+
    + +### Organization ID in the CLI + +Use [`influx org list`](#view-organizations-using-the-influx-cli) to view your organization ID. + +```sh +> influx org list + +ID Name +03a2bbf46249a000 org-1 +03ace3a859669000 org-2 +``` diff --git a/content/influxdb/v2.1/process-data/_index.md b/content/influxdb/v2.1/process-data/_index.md new file mode 100644 index 0000000000..cddc5062b1 --- /dev/null +++ b/content/influxdb/v2.1/process-data/_index.md @@ -0,0 +1,26 @@ +--- +title: Process Data with InfluxDB tasks +seotitle: Process Data with InfluxDB tasks +description: > + InfluxDB's task engine runs scheduled Flux tasks that process and analyze data. + This collection of articles provides information about creating and managing InfluxDB tasks. +menu: + influxdb_2_1: + name: Process data +weight: 6 +influxdb/v2.1/tags: [tasks] +--- + +Process and analyze your data with tasks in the InfluxDB **task engine**. Use tasks (scheduled Flux queries) +to input a data stream and then analyze, modify, and act on the data accordingly. + +Discover how to create and manage tasks using the InfluxDB user interface (UI) +and the `influx` command line interface (CLI). +Find examples of data downsampling, anomaly detection _(Coming)_, alerting +_(Coming)_, and other common tasks. + +{{% note %}} +Tasks replace InfluxDB v1.x continuous queries. +{{% /note %}} + +{{< children >}} diff --git a/content/influxdb/v2.1/process-data/common-tasks/_index.md b/content/influxdb/v2.1/process-data/common-tasks/_index.md new file mode 100644 index 0000000000..1542158c10 --- /dev/null +++ b/content/influxdb/v2.1/process-data/common-tasks/_index.md @@ -0,0 +1,17 @@ +--- +title: Common data processing tasks +seotitle: Common data processing tasks performed with with InfluxDB +description: > + InfluxDB Tasks process data on specified schedules. + This collection of articles walks through common use cases for InfluxDB tasks. +influxdb/v2.1/tags: [tasks] +menu: + influxdb_2_1: + name: Common tasks + parent: Process data +weight: 104 +--- + +The following articles walk through common task use cases. + +{{< children >}} diff --git a/content/influxdb/v2.1/process-data/common-tasks/calculate_weekly_mean.md b/content/influxdb/v2.1/process-data/common-tasks/calculate_weekly_mean.md new file mode 100644 index 0000000000..0ca0a1aef8 --- /dev/null +++ b/content/influxdb/v2.1/process-data/common-tasks/calculate_weekly_mean.md @@ -0,0 +1,49 @@ +--- +title: Calculate a weekly mean +description: > + Calculate a weekly mean and add it to a new bucket. +menu: + influxdb_2_1: + name: Calculate a weekly mean + parent: Common tasks +weight: 202 +influxdb/v2.1/tags: [tasks] +--- + +{{% note %}} +This example uses [NOAA water sample data](/influxdb/v2.1/reference/sample-data/#noaa-water-sample-data). +{{% /note %}} + +This example calculates a temperature weekly mean and stores it in a separate bucket. + +The following query: + - Uses [`filter()`](/{{< latest "flux" >}}/stdlib/universe/filter/) to filter the `average_temperature` measurement. + - Uses [`range()`](/{{< latest "flux" >}}/stdlib/universe/range/) to define a time range. + - Uses [`aggregateWindow()`](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow/) to group average temperature by week and compute the mean. + - Sends the weekly mean to a new bucket (`weekly_means`) + +```js +option task = { + name: "weekly-means", + every: 1w, +} + +from(bucket: "noaa") + |> filter(fn: (r) => r._measurement == "average_temperature") + |> range(start: 2019-09-01T11:24:00Z) + |> aggregateWindow(every: 1w, fn: mean) + |> to(bucket: "weekly_means") +``` +### Example results + +| _start | _stop | _field | _measurement | location | _value | _time | +|:------ |:----- |:------ |:------------ |:-------- | ------: |:----- | +| 2019-09-01T11:24:00Z | 2020-10-19T20:39:49Z | degrees | average_temperature | coyote_creek | 80.31005917159763 | 2019-09-05T00:00:00Z | +| 2019-09-01T11:24:00Z | 2020-10-19T20:39:49Z | degrees | average_temperature | coyote_creek | 79.8422619047619 | 2019-09-12T00:00:00Z | +| 2019-09-01T11:24:00Z | 2020-10-19T20:39:49Z | degrees | average_temperature | coyote_creek | 79.82710622710623 | 2019-09-19T00:00:00Z | + +| _start | _stop | _field | _measurement | location | _value | _time | +|:------ |:----- |:------ |:------------ |:-------- | ------: |:----- | +| 2019-09-01T11:24:00Z | 2020-10-19T20:39:49Z | degrees | average_temperature | santa_monica | 80.19952494061758 | 2019-09-05T00:00:00Z | +| 2019-09-01T11:24:00Z | 2020-10-19T20:39:49Z | degrees | average_temperature | santa_monica | 80.01964285714286 | 2019-09-12T00:00:00Z | +| 2019-09-01T11:24:00Z | 2020-10-19T20:39:49Z | degrees | average_temperature | santa_monica | 80.20451 diff --git a/content/influxdb/v2.1/process-data/common-tasks/convert_results_to_json.md b/content/influxdb/v2.1/process-data/common-tasks/convert_results_to_json.md new file mode 100644 index 0000000000..3dc65ab08c --- /dev/null +++ b/content/influxdb/v2.1/process-data/common-tasks/convert_results_to_json.md @@ -0,0 +1,43 @@ +--- +title: Convert results to JSON +seotitle: Convert results to JSON and send them to a URL +description: > + Use `json.encode()` to convert query results to JSON and `http.post()` to send them + to a URL endpoint. +menu: + influxdb_2_1: + name: Convert results to JSON + parent: Common tasks +weight: 203 +influxdb/v2.1/tags: [tasks] +--- +{{% note %}} +This example uses [NOAA water sample data](/influxdb/v2.1/reference/sample-data/#noaa-water-sample-data). +{{% /note %}} + +Send each record to a URL endpoint using the HTTP POST method. This example uses [`json.encode()`](/{{< latest "flux" >}}/stdlib/json/encode/) to convert a value into JSON bytes, then uses [`http.post()`](/{{< latest "flux" >}}/stdlib/http/post/) to send them to a URL endpoint. + +The following query: + - Uses [`filter()`](/{{< latest "flux" >}}/stdlib/universe/filter/) to filter the `average_temperature` measurement. + - Uses [`mean()`](/{{< latest "flux" >}}/stdlib/universe/mean/) to calculate the average value from results. + - Uses [`map()`](/{{< latest "flux" >}}/stdlib/universe/map/) to create a new column, `jsonStr`, and build a JSON object using column values from the query. It then byte-encodes the JSON object and stores it as a string in the `jsonStr` column. + - Uses [`http.post()`](/{{< latest "flux" >}}/stdlib/http/post/) to send the `jsonStr` value from each record to an HTTP endpoint. + + +```js +import "http" +import "json" + +from(bucket: "noaa") + |> filter(fn: (r) => r._measurement == "average_temperature") + |> mean() + |> map(fn: (r) => ({ r with + jsonStr: string(v: json.encode(v: {"location":r.location,"mean":r._value}))})) + |> map(fn: (r) => ({r with + status_code: http.post( + url: "http://somehost.com/", + headers: {x:"a", y:"b"}, + data: bytes(v: r.jsonStr) + ) + })) +``` diff --git a/content/influxdb/v2.1/process-data/common-tasks/downsample-data.md b/content/influxdb/v2.1/process-data/common-tasks/downsample-data.md new file mode 100644 index 0000000000..f27c5f7957 --- /dev/null +++ b/content/influxdb/v2.1/process-data/common-tasks/downsample-data.md @@ -0,0 +1,79 @@ +--- +title: Downsample data with InfluxDB +seotitle: Downsample data in an InfluxDB task +description: > + How to create a task that downsamples data much like continuous queries + in previous versions of InfluxDB. +menu: + influxdb_2_1: + name: Downsample data + parent: Common tasks +weight: 201 +influxdb/v2.1/tags: [tasks] +--- + +One of the most common use cases for InfluxDB tasks is downsampling data to reduce +the overall disk usage as data collects over time. +In previous versions of InfluxDB, continuous queries filled this role. + +This article walks through creating a continuous-query-like task that downsamples +data by aggregating data within windows of time, then storing the aggregate value in a new bucket. + +### Requirements +To perform a downsampling task, you need to the following: + +##### A "source" bucket +The bucket from which data is queried. + +##### A "destination" bucket +A separate bucket where aggregated, downsampled data is stored. + +##### Some type of aggregation +To downsample data, it must be aggregated in some way. +What specific method of aggregation you use depends on your specific use case, +but examples include mean, median, top, bottom, etc. +View [Flux's aggregate functions](/{{< latest "flux" >}}/function-types/#aggregates) +for more information and ideas. + +## Example downsampling task script +The example task script below is a very basic form of data downsampling that does the following: + +1. Defines a task named "cq-mem-data-1w" that runs once a week. +2. Defines a `data` variable that represents all data from the last 2 weeks in the + `mem` measurement of the `system-data` bucket. +3. Uses the [`aggregateWindow()` function](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow/) + to window the data into 1 hour intervals and calculate the average of each interval. +4. Stores the aggregated data in the `system-data-downsampled` bucket under the + `my-org` organization. + +```js +// Task Options +option task = { + name: "cq-mem-data-1w", + every: 1w, +} + +// Defines a data source +data = from(bucket: "system-data") + |> range(start: -duration(v: int(v: task.every) * 2)) + |> filter(fn: (r) => r._measurement == "mem") + +data + // Windows and aggregates the data in to 1h averages + |> aggregateWindow(fn: mean, every: 1h) + // Stores the aggregated data in a new bucket + |> to(bucket: "system-data-downsampled", org: "my-org") +``` + +Again, this is a very basic example, but it should provide you with a foundation +to build more complex downsampling tasks. + +## Add your task +Once your task is ready, see [Create a task](/influxdb/v2.1/process-data/manage-tasks/create-task) for information about adding it to InfluxDB. + +## Things to consider +- If there is a chance that data may arrive late, specify an `offset` in your + task options long enough to account for late-data. +- If running a task against a bucket with a finite retention period, + schedule tasks to run prior to the end of the retention period to let + downsampling tasks complete before data outside of the retention period is dropped. diff --git a/content/influxdb/v2.1/process-data/get-started.md b/content/influxdb/v2.1/process-data/get-started.md new file mode 100644 index 0000000000..b735526f1e --- /dev/null +++ b/content/influxdb/v2.1/process-data/get-started.md @@ -0,0 +1,163 @@ +--- +title: Get started with InfluxDB tasks +list_title: Get started with tasks +description: > + Learn the basics of writing an InfluxDB task that processes data, and then performs an action, + such as storing the modified data in a new bucket or sending an alert. +aliases: + - /influxdb/v2.1/process-data/write-a-task/ +influxdb/v2.1/tags: [tasks] +menu: + influxdb_2_1: + name: Get started with tasks + parent: Process data +weight: 101 +related: + - /influxdb/v2.1/process-data/manage-tasks/ + - /influxdb/v2.1/process-data/manage-tasks/create-task/ +--- + +An **InfluxDB task** is a scheduled Flux script that takes a stream of input data, modifies or analyzes +it in some way, then stores the modified data in a new bucket or performs other actions. + +This article walks through writing a basic InfluxDB task that downsamples +data and stores it in a new bucket. + +## Components of a task + +Every InfluxDB task needs the following four components. +Their form and order can vary, but they are all essential parts of a task. + +- [Task options](#define-task-options) +- [A data source](#define-a-data-source) +- [Data processing or transformation](#process-or-transform-your-data) +- [A destination](#define-a-destination) + +_[Skip to the full example task script](#full-example-task-script)_ + +## Define task options + +Task options define specific information about the task. +The example below illustrates how task options are defined in your Flux script: + +```js +option task = { + name: "cqinterval15m", + every: 1h, + offset: 0m, + concurrency: 1, +} +``` + +_See [Task configuration options](/influxdb/v2.1/process-data/task-options) for detailed information +about each option._ + +{{% note %}} +When creating a task in the InfluxDB user interface (UI), task options are defined in form fields. +{{% /note %}} + +## Define a data source + +Define a data source using Flux's [`from()` function](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/from/) +or any other [Flux input functions](/{{< latest "flux" >}}/function-types/#inputs). + +For convenience, consider creating a variable that includes the sourced data with +the required time range and any relevant filters. + +```js +data = from(bucket: "example-bucket") + |> range(start: -task.every) + |> filter(fn: (r) => + r._measurement == "mem" and + r.host == "myHost" + ) +``` + +{{% note %}} +#### Using task options in your Flux script + +Task options are passed as part of a `task` option record and can be referenced in your Flux script. +In the example above, the time range is defined as `-task.every`. + +`task.every` is dot notation that references the `every` property of the `task` option record. +`every` is defined as `1h`, therefore `-task.every` equates to `-1h`. + +Using task options to define values in your Flux script can make reusing your task easier. +{{% /note %}} + +## Process or transform your data + +The purpose of tasks is to process or transform data in some way. +What exactly happens and what form the output data takes is up to you and your +specific use case. + +{{% note %}} +#### Account for latent data with an offset + +To account for latent data (like data streaming from your edge devices), use an offset in your task. For example, if you set a task interval on the hour with the options `every: 1h` and `offset: 5m`, a task executes 5 minutes after the task interval but the query [`now()`](/{{< latest "flux" >}}/stdlib/universe/now/) time is on the exact hour. + +{{% /note %}} + +The example below illustrates a task that downsamples data by calculating the average of set intervals. +It uses the `data` variable defined [above](#define-a-data-source) as the data source. +It then windows the data into 5 minute intervals and calculates the average of each +window using the [`aggregateWindow()` function](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow/). + +```js +data + |> aggregateWindow( + every: 5m, + fn: mean + ) +``` + +_See [Common tasks](/influxdb/v2.1/process-data/common-tasks) for examples of tasks commonly used with InfluxDB._ + +## Define a destination + +In the vast majority of task use cases, once data is transformed, it needs to be sent and stored somewhere. +This could be a separate bucket or another measurement. + +The example below uses Flux's [`to()` function](/{{< latest "flux" >}}/stdlib/universe/to) +to send the transformed data to another bucket: + +```js +// ... +|> to(bucket: "example-downsampled", org: "my-org") +``` + +{{% note %}} +In order to write data into InfluxDB, you must have `_time`, `_measurement`, `_field`, and `_value` columns. +{{% /note %}} + +## Full example task script + +Below is a task script that combines all of the components described above: + +```js +// Task options +option task = { + name: "cqinterval15m", + every: 1h, + offset: 0m, + concurrency: 1, +} + +// Data source +data = from(bucket: "example-bucket") + |> range(start: -task.every) + |> filter(fn: (r) => + r._measurement == "mem" and + r.host == "myHost" + ) + +data + // Data transformation + |> aggregateWindow( + every: 5m, + fn: mean + ) + // Data destination + |> to(bucket: "example-downsampled") + +``` diff --git a/content/influxdb/v2.1/process-data/manage-tasks/_index.md b/content/influxdb/v2.1/process-data/manage-tasks/_index.md new file mode 100644 index 0000000000..3c3d9d743e --- /dev/null +++ b/content/influxdb/v2.1/process-data/manage-tasks/_index.md @@ -0,0 +1,20 @@ +--- +title: Manage tasks in InfluxDB +seotitle: Manage data processing tasks in InfluxDB +list_title: Manage tasks +description: > + InfluxDB provides options for creating, reading, updating, and deleting tasks + using both the `influx` CLI and the InfluxDB UI. +influxdb/v2.1/tags: [tasks] +menu: + influxdb_2_1: + name: Manage tasks + parent: Process data +weight: 102 +--- + +InfluxDB provides two options for managing the creation, reading, updating, and deletion (CRUD) of tasks - +through the InfluxDB user interface (UI) or using the `influx` command line interface (CLI). +Both tools can perform all task CRUD operations. + +{{< children >}} diff --git a/content/influxdb/v2.1/process-data/manage-tasks/create-task.md b/content/influxdb/v2.1/process-data/manage-tasks/create-task.md new file mode 100644 index 0000000000..2fc16c5ff4 --- /dev/null +++ b/content/influxdb/v2.1/process-data/manage-tasks/create-task.md @@ -0,0 +1,152 @@ +--- +title: Create a task +seotitle: Create a task for processing data in InfluxDB +description: > + Create a data processing task in InfluxDB using the InfluxDB UI or the `influx` CLI. +menu: + influxdb_2_1: + name: Create a task + parent: Manage tasks +weight: 201 +related: + - /influxdb/v2.1/reference/cli/influx/task/create +--- + +InfluxDB provides multiple ways to create tasks both in the InfluxDB user interface (UI) +and the `influx` command line interface (CLI). + +_Before creating a task, review the [basics criteria for writing a task](/influxdb/v2.1/process-data/get-started)._ + +- [InfluxDB UI](#create-a-task-in-the-influxdb-ui) +- [`influx` CLI](#create-a-task-using-the-influx-cli) +- [InfluxDB API](#create-a-task-using-the-influxdb-api) + +## Create a task in the InfluxDB UI +The InfluxDB UI provides multiple ways to create a task: + +- [Create a task from the Data Explorer](#create-a-task-from-the-data-explorer) +- [Create a task in the Task UI](#create-a-task-in-the-task-ui) +- [Import a task](#import-a-task) +- [Create a task from a template](#create-a-task-from-a-template) +- [Clone a task](#clone-a-task) + +### Create a task from the Data Explorer +1. In the navigation menu on the left, select **Explore** (**Data Explorer**). + + {{< nav-icon "data-explorer" >}} + +2. Build a query and click **Save As** in the upper right. +3. Select the **Task** option. +4. Specify the task options. See [Task options](/influxdb/v2.1/process-data/task-options) + for detailed information about each option. +5. Select a token to use from the **Token** dropdown. +6. Click **Save as Task**. + + +### Create a task in the Task UI +1. In the navigation menu on the left, select **Tasks**. + + {{< nav-icon "tasks" >}} + +2. Click **{{< icon "plus" >}} Create Task** in the upper right. +3. Select **New Task**. +4. In the left panel, specify the task options. + See [Task options](/influxdb/v2.1/process-data/task-options) for detailed information about each option. +5. Select a token to use from the **Token** dropdown. +6. In the right panel, enter your task script. + + {{% note %}} +##### Leave out the option tasks assignment +When creating a _new_ task in the InfluxDB Task UI, leave out the `option task` +assignment that defines [task options](/influxdb/v2.1/process-data/task-options/). +The InfluxDB UI injects this code using settings specified in the **Task options** +fields in the left panel when you save the task. + {{% /note %}} + +7. Click **Save** in the upper right. + +### Import a task +1. In the navigation menu on the left, select **Tasks**. + + {{< nav-icon "tasks" >}} + +2. Click **+ Create Task** in the upper right. +3. Select **Import Task**. +4. Upload a JSON task file using one of the following options: + - Drag and drop a JSON task file in the specified area. + - Click to upload and the area to select the JSON task from from your file manager. + - Select the **JSON** option and paste in raw task JSON. +5. Click **Import JSON as Task**. + +### Create a task from a template +1. In the navigation menu on the left, select **Settings** > **Templates**. + + {{< nav-icon "Settings" >}} + +2. Select **Templates**. +3. Hover over the template to use to create the task and click **Create**. + + +### Clone a task +1. In the navigation menu on the left, select **Tasks**. + + {{< nav-icon "tasks" >}} + +2. Hover over the task you would like to clone and click the **{{< icon "duplicate" >}}** icon that appears. +4. Click **Clone**. + +## Create a task using the influx CLI +Use `influx task create` command to create a new task. +It accepts either a file path or raw Flux. + +###### Create a task using a file +```sh +# Syntax +influx task create --org -f + +# Example +influx task create --org my-org -f /tasks/cq-mean-1h.flux +``` + +###### Create a task using raw Flux +```sh +influx task create --org my-org - # to open stdin pipe + +option task = { + name: "task-name", + every: 6h +} + +# ... Task script ... + +# to close the pipe and submit the command +``` + +## Create a task using the InfluxDB API + +Send a request using the **POST** method to the `/api/v2/tasks` InfluxDB API endpoint. +Provide the following in your API request: + +##### Request headers +- **Content-Type**: application/json +- **Authorization**: Token _YOURINFLUXDBTOKEN_** + +##### Request body +JSON object with the following fields: + +- **flux** : raw Flux task string +- **orgID**: your [InfluxDB organization ID](/influxdb/v2.1/organizations/view-orgs/#view-your-organization-id) +- **status**: task status ("active" or "inactive") +- **description**: task description + +```sh +curl --request POST 'https://us-west-2-1.aws.cloud2.influxdata.com/api/v2/tasks' \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Token ' \ + --data-raw '{ + "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\n\nfrom(bucket: \"telegraf\")\n\t|> range(start: -1h)\n\t|> filter(fn: (r) =>\n\t\t(r._measurement == \"cpu\"))\n\t|> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\"))\n\t|> filter(fn: (r) =>\n\t\t(r.cpu == \"cpu-total\"))\n\t|> aggregateWindow(every: 1h, fn: max)\n\t|> to(bucket: \"cpu_usage_user_total_1h\", org: \"\")", + "orgID": "", + "status": "active", + "description": "This task downsamples CPU data every hour" +}' +``` diff --git a/content/influxdb/v2.1/process-data/manage-tasks/delete-task.md b/content/influxdb/v2.1/process-data/manage-tasks/delete-task.md new file mode 100644 index 0000000000..baf8620269 --- /dev/null +++ b/content/influxdb/v2.1/process-data/manage-tasks/delete-task.md @@ -0,0 +1,36 @@ +--- +title: Delete a task +seotitle: Delete a task for processing data in InfluxDB +description: > + Delete a task from InfluxDB using the InfluxDB UI or the `influx` CLI. +menu: + influxdb_2_1: + name: Delete a task + parent: Manage tasks +weight: 206 +related: + - /influxdb/v2.1/reference/cli/influx/task/delete +--- + +## Delete a task in the InfluxDB UI +1. In the navigation menu on the left, select **Tasks**. + + {{< nav-icon "tasks" >}} + +2. In the list of tasks, hover over the task you would like to delete. +3. Click **Delete** on the far right. +4. Click **Confirm**. + + +## Delete a task with the influx CLI +Use the `influx task delete` command to delete a task. + +_This command requires a task ID, which is available in the output of `influx task list`._ + +```sh +# Syntax +influx task delete -i + +# Example +influx task delete -i 0343698431c35000 +``` diff --git a/content/influxdb/v2.1/process-data/manage-tasks/export-task.md b/content/influxdb/v2.1/process-data/manage-tasks/export-task.md new file mode 100644 index 0000000000..b5d0820e8b --- /dev/null +++ b/content/influxdb/v2.1/process-data/manage-tasks/export-task.md @@ -0,0 +1,26 @@ +--- +title: Export a task +seotitle: Export an InfluxDB task +description: Export a data processing task from InfluxDB using the InfluxDB UI. +menu: + influxdb_2_1: + name: Export a task + parent: Manage tasks +weight: 205 +--- + +InfluxDB lets you export tasks from the InfluxDB user interface (UI). +Tasks are exported as downloadable JSON files. + +## Export a task in the InfluxDB UI +1. In the navigation menu on the left, select **Tasks**. + + {{< nav-icon "tasks" >}} + +2. In the list of tasks, hover over the task you would like to export and click + the **{{< icon "gear" >}}** icon that appears. +3. Select **Export**. +4. Downloading or save the task export file using one of the following options: + - Click **Download JSON** to download the exported JSON file. + - Click **Save as template** to save the export file as a task template. + - Click **Copy to Clipboard** to copy the raw JSON content to your machine's clipboard. diff --git a/content/influxdb/v2.1/process-data/manage-tasks/run-task.md b/content/influxdb/v2.1/process-data/manage-tasks/run-task.md new file mode 100644 index 0000000000..713d579901 --- /dev/null +++ b/content/influxdb/v2.1/process-data/manage-tasks/run-task.md @@ -0,0 +1,66 @@ +--- +title: Run a task +seotitle: Run an InfluxDB task +description: > + Run a data processing task using the InfluxDB UI or the `influx` CLI. +menu: + influxdb_2_1: + name: Run a task + parent: Manage tasks +weight: 203 +related: + - /influxdb/v2.1/reference/cli/influx/task/run + - /influxdb/v2.1/reference/cli/influx/task/run/retry + - /influxdb/v2.1/reference/cli/influx/task/retry-failed +--- + +InfluxDB data processing tasks generally run in defined intervals or at a specific time, +however, you can manually run a task from the InfluxDB user interface (UI) or the +`influx` command line interface (CLI). + +## Run a task from the InfluxDB UI +1. In the navigation menu on the left, select **Tasks**. + + {{< nav-icon "tasks" >}} + +2. Hover over the task you want to run and click the **{{< icon "gear" >}}** icon. +3. Select **Run Task**. + +## Run a task with the influx CLI +Use the `influx task run retry` command to run a task. + +{{% note %}} +To run a task from the `influx` CLI, the task must have already run at least once. +{{% /note %}} + +{{< cli/influx-creds-note >}} + +```sh +# List all tasks to find the ID of the task to run +influx task list + +# Use the task ID to list previous runs of the task +influx task run list --task-id=0000000000000000 + +# Use the task ID and run ID to retry a run +influx task run retry --task-id=0000000000000000 --run-id=0000000000000000 +``` + +### Retry failed task runs +Use the [`influx task retry-failed` command](/influxdb/v2.1/reference/cli/influx/task/retry-failed/) +to retry failed task runs. + +```sh +# Retry failed tasks for a specific task +influx task retry-failed \ + --id 0000000000000000 + +# Print information about runs that will be retried +influx task retry-failed \ + --dry-run + +# Retry failed task runs that occurred in a specific time range +influx task retry-failed \ + --after 2021-01-01T00:00:00Z \ + --before 2021-01-01T23:59:59Z +``` diff --git a/content/influxdb/v2.1/process-data/manage-tasks/task-run-history.md b/content/influxdb/v2.1/process-data/manage-tasks/task-run-history.md new file mode 100644 index 0000000000..fd0e7c855b --- /dev/null +++ b/content/influxdb/v2.1/process-data/manage-tasks/task-run-history.md @@ -0,0 +1,67 @@ +--- +title: View task run history and logs +description: > + View task run histories and logs using the InfluxDB UI or the `influx` CLI. +menu: + influxdb_2_1: + name: View run history + parent: Manage tasks +weight: 203 +related: + - /influxdb/v2.1/reference/cli/influx/task/list + - /influxdb/v2.1/reference/cli/influx/task/run/list + - /influxdb/v2.1/reference/cli/influx/task/retry-failed +--- + +When an InfluxDB task runs, a "run" record is created in the task's history. +Logs associated with each run provide relevant log messages, timestamps, +and the exit status of the run attempt. + +Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) +to view task run histories and associated logs. + +## View a task's run history in the InfluxDB UI + +1. In the navigation menu on the left, select **Tasks**. + + {{< nav-icon "tasks" >}} + +2. Hover over the task you want to run and click the **{{< icon "gear" >}}** icon. +3. Select **View Task Runs**. + +### View task run logs +To view logs associated with a run, click **View Logs** next to the run in the task's run history. + +## View a task's run history with the influx CLI +Use the `influx task run list` command to view a task's run history. + +```sh +# List all tasks to find the ID of the task to run +influx task list + +# Use the task ID to view the run history of a task +influx task run list --task-id=0000000000000000 +``` + +{{% note %}} +Detailed run logs are not currently available in the `influx` CLI. +{{% /note %}} + +## Retry failed task runs +Use the [`influx task retry-failed` command](/influxdb/v2.1/reference/cli/influx/task/retry-failed/) +to retry failed task runs. + +```sh +# Retry failed tasks for a specific task +influx task retry-failed \ + --id 0000000000000000 + +# Print information about runs that will be retried +influx task retry-failed \ + --dry-run + +# Retry failed task runs that occurred in a specific time range +influx task retry-failed \ + --after 2021-01-01T00:00:00Z \ + --before 2021-01-01T23:59:59Z +``` diff --git a/content/influxdb/v2.1/process-data/manage-tasks/update-task.md b/content/influxdb/v2.1/process-data/manage-tasks/update-task.md new file mode 100644 index 0000000000..39fce5d8a9 --- /dev/null +++ b/content/influxdb/v2.1/process-data/manage-tasks/update-task.md @@ -0,0 +1,69 @@ +--- +title: Update a task +seotitle: Update a task for processing data in InfluxDB +description: > + Update a data processing task in InfluxDB using the InfluxDB UI or the `influx` CLI. +menu: + influxdb_2_1: + name: Update a task + parent: Manage tasks +weight: 204 +related: + - /influxdb/v2.1/reference/cli/influx/task/update +--- + +## Update a task in the InfluxDB UI +Click the **Tasks** icon in the left navigation to view the lists of tasks. + +{{< nav-icon "tasks" >}} + +Click the name of a task to update it. + +#### Update a task Flux script +1. In the list of tasks, click the **Name** of the task you want to update. +2. In the left panel, modify the task options. +3. In the right panel, modify the task script. +4. Click **Save** in the upper right. + + +#### Update the status of a task +In the list of tasks, click the {{< icon "toggle" >}} toggle to the left of the +task you want to activate or inactivate. + +#### Update a task description +1. In the list of tasks, hover over the name of the task you want to update. +2. Click the pencil icon {{< icon "pencil" >}}. +3. Click outside of the field or press `RETURN` to update. + +## Update a task with the influx CLI +Use the `influx task update` command to update or change the status of an existing task. + +_This command requires a task ID, which is available in the output of `influx task list`._ + +#### Update a task Flux script +Pass the file path of your updated Flux script to the `influx task update` command +with the ID of the task you want to update. +Modified [task options](/influxdb/v2.1/process-data/task-options) defined in the Flux +script are also updated. + +```sh +# Syntax +influx task update -i -f + +# Example +influx task update -i 0343698431c35000 -f /tasks/cq-mean-1h.flux +``` + +#### Update the status of a task +Pass the ID of the task you want to update to the `influx task update` +command with the `--status` flag. + +_Possible arguments of the `--status` flag are `active` or `inactive`._ + +```sh +# Syntax +influx task update -i --status < active | inactive > + +# Example +influx task update -i 0343698431c35000 --status inactive +``` diff --git a/content/influxdb/v2.1/process-data/manage-tasks/view-tasks.md b/content/influxdb/v2.1/process-data/manage-tasks/view-tasks.md new file mode 100644 index 0000000000..864a8d32d2 --- /dev/null +++ b/content/influxdb/v2.1/process-data/manage-tasks/view-tasks.md @@ -0,0 +1,38 @@ +--- +title: View tasks +seotitle: View created tasks that process data in InfluxDB +description: > + View existing data processing tasks using the InfluxDB UI or the `influx` CLI. +menu: + influxdb_2_1: + name: View tasks + parent: Manage tasks +weight: 202 +related: + - /influxdb/v2.1/reference/cli/influx/task/list +--- + +## View tasks in the InfluxDB UI +Click the **Tasks** icon in the left navigation to view the lists of tasks. + +{{< nav-icon "tasks" >}} + +### Filter the list of tasks + +1. Click the **Show Inactive** {{< icon "toggle" >}} toggle to include or exclude + inactive tasks in the list. +2. Enter text in the **Filter tasks** field to search for tasks by name or label. +3. Click the heading of any column to sort by that field. + +## View tasks with the influx CLI +Use the `influx task list` command to return a list of created tasks. + +```sh +influx task list +``` + +#### Filter tasks using the CLI +Other filtering options such as filtering by organization or user, +or limiting the number of tasks returned, are available. +See the [`influx task list` documentation](/influxdb/v2.1/reference/cli/influx/task/list) +for information about other available flags. diff --git a/content/influxdb/v2.1/process-data/task-options.md b/content/influxdb/v2.1/process-data/task-options.md new file mode 100644 index 0000000000..dc8278292b --- /dev/null +++ b/content/influxdb/v2.1/process-data/task-options.md @@ -0,0 +1,107 @@ +--- +title: Task configuration options +seotitle: InfluxDB task configuration options +description: > + Task options define specific information about a task such as its name, + the schedule on which it runs, execution delays, and others. +menu: + influxdb_2_1: + name: Task options + parent: Process data +weight: 105 +influxdb/v2.1/tags: [tasks, flux] +--- + +Task options define specific information about a task. +They are set in a Flux script or in the InfluxDB user interface (UI). +The following task options are available: + +- [name](#name) +- [every](#every) +- [cron](#cron) +- [offset](#offset) +- [concurrency](#concurrency) + +{{% note %}} +`every` and `cron` are mutually exclusive, but at least one is required. +{{% /note %}} + +## name +The name of the task. _**Required**_. + +_**Data type:** String_ + +```js +option task = { + name: "taskName", + // ... +} +``` + +## every + +The interval at which the task runs. This option also determines when the task first starts to run, depending on the specified time (in [duration literal](/{{< latest "flux" >}}/spec/lexical-elements/#duration-literals)). + +_**Data type:** Duration_ + +```js +option task = { + // ... + every: 1h, +} +``` + +For example, if you save or schedule a task at 2:30 and run the task every hour (`1h`): + +`option task = {name: "aggregation", every: 1h}` + +The task first executes at 3:00pm, and subsequently every hour after that. + +{{% note %}} +In the InfluxDB UI, the **Interval** field sets this option. +{{% /note %}} + +## cron +The [cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that +defines the schedule on which the task runs. +Cron scheduling is based on system time. + +_**Data type:** String_ + +```js +option task = { + // ... + cron: "0 * * * *", +} +``` + +## offset + +Delays the execution of the task but preserves the original time range. +For example, if a task is to run on the hour, a `10m` offset will delay it to 10 +minutes after the hour, but all time ranges defined in the task are relative to +the specified execution time. +A common use case is offsetting execution to account for data that may arrive late. + +_**Data type:** Duration_ + +```js +option task = { + // ... + offset: 10m, +} +``` + +## concurrency +The number task of executions that can run concurrently. +If the concurrency limit is reached, all subsequent executions are queued until +other running task executions complete. + +_**Data type:** Integer_ + +```js +option task = { + // ... + concurrency: 2, +} +``` diff --git a/content/influxdb/v2.1/query-data/_index.md b/content/influxdb/v2.1/query-data/_index.md new file mode 100644 index 0000000000..6c585d5196 --- /dev/null +++ b/content/influxdb/v2.1/query-data/_index.md @@ -0,0 +1,17 @@ +--- +title: Query data in InfluxDB +seotitle: Query data stored in InfluxDB +description: > + Learn to query data stored in InfluxDB using Flux and tools such as the InfluxDB + user interface and the 'influx' command line interface. +menu: + influxdb_2_1: + name: Query data +weight: 5 +influxdb/v2.1/tags: [query, flux] +--- + +Learn to query data stored in InfluxDB using Flux and tools such as the InfluxDB +user interface and the 'influx' command line interface. + +{{< children >}} diff --git a/content/influxdb/v2.1/query-data/common-queries/_index.md b/content/influxdb/v2.1/query-data/common-queries/_index.md new file mode 100644 index 0000000000..f8777ea28f --- /dev/null +++ b/content/influxdb/v2.1/query-data/common-queries/_index.md @@ -0,0 +1,22 @@ +--- +title: Common queries +seotitle: Common queries with Flux +description: > + This collection of articles walks through common use cases for Flux queries. +influxdb/v2.1/tags: [queries] +menu: + influxdb_2_1: + name: Common queries + parent: Query data +weight: 104 +--- + +The following articles walk through common queries using the +[NOAA water database data](/influxdb/v2.1/reference/sample-data/#noaa-water-sample-data). + +{{< children >}} + +{{% note %}} +This list will continue to grow. +If you have suggestions, please [submit them to the InfluxData Community](https://community.influxdata.com/c/influxdb2). +{{% /note %}} diff --git a/content/influxdb/v2.1/query-data/common-queries/compare-values.md b/content/influxdb/v2.1/query-data/common-queries/compare-values.md new file mode 100644 index 0000000000..1aa5bf6ac4 --- /dev/null +++ b/content/influxdb/v2.1/query-data/common-queries/compare-values.md @@ -0,0 +1,48 @@ +--- +title: Comparing values from different buckets +seotitle: Compare the last measurement to a mean stored in another bucket +description: > + Compare the value from the latest point to an average value stored in another bucket. This is useful when using the average value to calculate a threshold check. +influxdb/v2.1/tags: [queries] +menu: + influxdb_2_1: + name: Compare values from different buckets + parent: Common queries +weight: 104 +--- + +{{% note %}} +This example uses [NOAA water sample data](/influxdb/v2.1/reference/sample-data/#noaa-water-sample-data). +{{% /note %}} + +This example compares the value from the latest point to an average value stored in another bucket. This is useful when using the average value to calculate a [threshold check](/influxdb/v2.1/monitor-alert/checks/create/#threshold-check). + +The following query: + + - Uses [`range()`](/{{< latest "flux" >}}/stdlib/universe/range/) to define a time range. + - Gets the last value in the `means` bucket and compares it to the last value in the `noaa` bucket using [`last()`](/{{< latest "flux" >}}/stdlib/universe/last/). + - Uses [`join()`](/{{< latest "flux" >}}/stdlib/universe/join/) to combine the results + - Uses [`map()`](/{{< latest "flux" >}}/stdlib/universe/map/) to calculate the differences + + ```js + means = from(bucket: "weekly_means") + |> range(start: 2019-09-01T00:00:00Z) + |> last() + |> keep(columns: ["_value", "location"]) + + latest = from(bucket: "noaa") + |> range(start: 2019-09-01T00:00:00Z) + |> filter(fn: (r) => r._measurement == "average_temperature") + |> last() + |> keep(columns: ["_value", "location"]) + + join(tables: {mean: means, reading: latest}, on: ["location"]) + |> map(fn: (r) => ({r with deviation: r._value_reading - r._value_mean})) + ``` + +### Example results + +| location | _value_mean | _value_reading | deviation | +|:-------- | -----------: | --------------:| ---------: | +| coyote_creek | 79.82710622710623 | 89 | 9.172893772893772 | +| santa_monica | 80.20451339915374 | 85 | 4.79548660084626 | diff --git a/content/influxdb/v2.1/query-data/common-queries/iot-common-queries.md b/content/influxdb/v2.1/query-data/common-queries/iot-common-queries.md new file mode 100644 index 0000000000..e85ce78153 --- /dev/null +++ b/content/influxdb/v2.1/query-data/common-queries/iot-common-queries.md @@ -0,0 +1,215 @@ +--- +title: IoT sensor common queries +description: > + Use Flux to address common IoT use cases that query data collected from sensors. +influxdb/v2.1/tags: [queries] +menu: + influxdb_2_1: + name: IoT common queries + parent: Common queries +weight: 205 +--- + +The following scenarios illustrate common queries used to extract information from IoT sensor data: + +- [Calculate time in state](#calculate-time-in-state) +- [Calculate time weighted average](#calculate-time-weighted-average) +- [Calculate value between events](#calculate-value-between-events) +- [Determine a state within existing values](#determine-a-state-within-existing-values) + +All scenarios below use the `machineProduction` sample dataset provided by the [InfluxDB `sample` package](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/sample/). +For more information, see [Sample data](/influxdb/cloud/reference/sample-data/). + +## Calculate time in state + +In this scenario, we look at whether a production line is running smoothly (`state`=`OK`) and what percentage of time the production line is running smoothly or not (`state`=`NOK`). If no points are recorded during the interval (`state`=`NaN`), you may opt to retrieve the last state prior to the interval. + +To visualize the time in state, see the [Mosaic visualization](#mosaic-visualization). + +**To calculate the percentage of time a machine spends in each state** + +1. Import the [`contrib/tomhollingworth/events` package](/{{< latest "flux" >}}/stdlib/contrib/tomhollingworth/events/). +1. Query the `state` field. +2. Use `events.duration()` to return the amount of time (in a specified unit) between each data point, and store the interval in the `duration` column. +3. Group columns by the status value column (in this case `_value`), `_start`, `_stop`, and other relevant dimensions. +4. Sum the `duration` column to calculate the total amount of time spent in each state. +5. Pivot the summed durations into the `_value` column. +6. Use `map()` to calculate the percentage of time spent in each state. + +```js +import "contrib/tomhollingworth/events" + +from(bucket: "machine") + |> range(start: 2021-08-01T00:00:00Z, stop: 2021-08-02T00:30:00Z) + |> filter(fn: (r) => r["_measurement"] == "machinery") + |> filter(fn: (r) => r["_field"] == "state") + |> events.duration(unit: 1h, columnName: "duration",) + |> group(columns: ["_value", "_start", "_stop", "station_id"]) + |> sum(column: "duration") + |> pivot(rowKey:["_stop"], columnKey: ["_value"], valueColumn: "duration") + |> map(fn: (r) => { + totalTime = float(v: r.NOK + r.OK) + return {r with NOK: float(v: r.NOK) / totalTime * 100.0, OK: float(v: r.OK) / totalTime * 100.0} + }) +``` + +The query above focuses on a specific time range of state changes reported in the production line. + +- `range()` defines the time range to query. +- `filter()` defines the field (`state`) and measurement (`machinery`) to filter by. +- `events.duration()` calculates the time between points. +- `group()` regroups the data by the field value, so points with `OK` and `NOK` field values are grouped into separate tables. +- `sum()` returns the sum of durations spent in each state. + +The output of the query at this point is: + +| _value | duration | +| ------ | -------: | +| NOK | 22 | + +| _value | duration | +| ------ | -------: | +| OK | 172 | + +`pivot()` creates columns for each unique value in the `_value` column, and then assigns the associated duration as the column value. +The output of the pivot operation is: + +| NOK | OK | +| :-- | :-- | +| 22 | 172 | + +Given the output above, `map()` does the following: + +1. Adds the `NOK` and `OK` values to calculate `totalTime`. +2. Divides `NOK` by `totalTime`, and then multiplies the quotient by 100. +3. Divides `OK` by `totalTime`, and then multiplies the quotient by 100. + +This returns: + +| NOK | OK | +| :---------------- | :----------------- | +| 11.34020618556701 | 88.65979381443299 | + +The result shows that 88.66% of time production is in the `OK` state, and that 11.34% of time, production is in the `NOK` state. + +#### Mosaic visualization + +The [mosaic visualization](/influxdb/v2.1/visualize-data/visualization-types/mosaic/) displays state changes over time. In this example, the mosaic visualization displays different colored tiles based on the `state` field. + +```js +from(bucket: "machine") + |> range(start: 2021-08-01T00:00:00Z, stop: 2021-08-02T00:30:00Z) + |> filter(fn: (r) => r._measurement == "machinery") + |> filter(fn: (r) => r._field == "state") + |> aggregateWindow(every: v.windowPeriod, fn: last, createEmpty: false) +``` + +When visualizing data, it is possible to have more data points than available pixels. To divide data into time windows that span a single pixel, use `aggregateWindow` with the `every` parameter set to `v.windowPeriod`. +Use `last` as the aggregate `fn` to return the last value in each time window. +Set `createEmpty` to `false` so results won't include empty time windows. + + +## Calculate time weighted average + +To calculate the time-weighted average of data points, use the [`timeWeightedAvg()` function](/{{< latest "flux" >}}/stdlib/universe/timeweightedavg/). + +The example below queries the `oil_temp` field in the `machinery` measurement. The `timeWeightedAvg()` function returns the time-weighted average of oil temperatures based on 5 second intervals. + +```js +from(bucket: "machine") + |> range(start: 2021-08-01T00:00:00Z, stop: 2021-08-01T00:00:30Z) + |> filter(fn: (r) => + r._measurement == "machinery" and r._field == "oil_temp" + ) + |> timeWeightedAvg(unit: 5s) +``` + +##### Output data + +| stationID | _start | _stop | _value | +|:----- | ----- | ----- | ------:| +| g1 | 2021-08-01T01:00:00.000Z | 2021-08-01T00:00:30.000Z | 40.25396118491921 | +| g2 | 2021-08-01T01:00:00.000Z | 2021-08-01T00:00:30.000Z | 40.6 | +| g3 | 2021-08-01T01:00:00.000Z | 2021-08-01T00:00:30.000Z | 41.384505595567866 | +| g4 | 2021-08-01T01:00:00.000Z | 2021-08-01T00:00:30.000Z | 41.26735518634935 | + + +## Calculate value between events + +Calculate the value between events by getting the average value during a specific time range. + +The following scenario queries data starting when four production lines start and end. +The following query calculates the average oil temperature for each grinding station during that period. + +```js +batchStart = 2021-08-01T00:00:00Z +batchStop = 2021-08-01T00:00:20Z + +from(bucket: "machine") + |> range(start: batchStart, stop: batchStop) + |> filter(fn: (r) => + r._measurement == "machinery" and + r._field == "oil_temp" + ) + |> mean() +``` + +##### Output + +| stationID | _start | _stop | _value | +|:----- | ----- | ----- | ------:| +| g1 | 2021-08-01T01:00:00.000Z | 2021-08-02T00:00:00.000Z | 40 | +| g2 | 2021-08-01T01:00:00.000Z | 2021-08-02T00:00:00.000Z | 40.6 | +| g3 | 2021-08-01T01:00:00.000Z | 2021-08-02T00:00:00.000Z | 41.379999999999995 | +| g4 | 2021-08-01T01:00:00.000Z | 2021-08-02T00:00:00.000Z | 41.2 | + + +## Determine a state with existing values + +Use multiple existing values to determine a state. +The following example calculates a state based on the difference between the `pressure` and `pressure-target` fields in the machine-production sample data. +To determine a state by comparing existing fields: + +1. Query the fields to compare (in this case, `pressure` and `pressure_target`). +2. (Optional) Use `aggregateWindow()` to window data into time-based windows and + apply an aggregate function (like `mean()`) to return values that represent larger windows of time. +3. Use `pivot()` to shift field values into columns. +4. Use `map()` to compare or operate on the different field column values. +5. Use `map()` to assign a status (in this case, `needsMaintenance` based on the relationship of the field column values. + +```js +import "math" + +from(bucket: "machine") + |> range(start: 2021-08-01T00:00:00Z, stop: 2021-08-02T00:00:00Z) + |> filter(fn: (r) => r["_measurement"] == "machinery") + |> filter(fn: (r) => r["_field"] == "pressure" or r["_field"] == "pressure_target") + |> aggregateWindow(every: 12h, fn: mean) + |> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") + |> map(fn: (r) => ({ r with pressureDiff: r.pressure - r.pressure_target })) + |> map(fn: (r) => ({ r with needsMaintenance: if math.abs(x: r.pressureDiff) >= 15.0 then true else false })) +``` + +##### Output + +| _time | needsMaintenance | pressure | pressure_target | pressureDiff | stationID | +| :----------------------- | :--------------- | -----------------: | -----------------: | ------------------: | --------: | +| 2021-08-01T12:00:00.000Z | false | 101.83929080014092 | 104.37786394078252 | -2.5385731406416028 | g1 | +| 2021-08-02T00:00:00.000Z | false | 96.04368008245874 | 102.27698650674662 | -6.233306424287889 | g1 | + +| _time | needsMaintenance | pressure | pressure_target | pressureDiff | stationID | +| :----------------------- | :--------------- | -----------------: | -----------------: | ------------------: | --------: | +| 2021-08-01T12:00:00.000Z | false | 101.62490431541765 | 104.83915260886623 | -3.214248293448577 | g2 | +| 2021-08-02T00:00:00.000Z | false | 94.52039415465273 | 105.90869375273046 | -11.388299598077722 | g2 | + +| _time | needsMaintenance | pressure | pressure_target | pressureDiff | stationID | +| :----------------------- | :--------------- | -----------------: | -----------------: | ------------------: | --------: | +| 2021-08-01T12:00:00.000Z | false | 92.23774168403503 | 104.81867444768653 | -12.580932763651504 | g3 | +| 2021-08-02T00:00:00.000Z | true | 89.20867846153847 | 108.2579185520362 | -19.049240090497733 | g3 | + +| _time | needsMaintenance | pressure | pressure_target | pressureDiff | stationID | +| :----------------------- | :--------------- | -----------------: | -----------------: | ------------------: | --------: | +| 2021-08-01T12:00:00.000Z | false | 94.40834093349847 | 107.6827757125155 | -13.274434779017028 | g4 | +| 2021-08-02T00:00:00.000Z | true | 88.61785638936534 | 108.25471698113208 | -19.636860591766734 | g4 | + +The table reveals that the `pressureDiff` value `-19.636860591766734` from station g4 and `-19.049240090497733` from station g3 are higher than 15, therefore there is a change in state that marks the `needMaintenance` value as "true" and would require that station to need work to turn that value back to `false`. \ No newline at end of file diff --git a/content/influxdb/v2.1/query-data/common-queries/multiple-fields-in-calculations.md b/content/influxdb/v2.1/query-data/common-queries/multiple-fields-in-calculations.md new file mode 100644 index 0000000000..8e676ebda0 --- /dev/null +++ b/content/influxdb/v2.1/query-data/common-queries/multiple-fields-in-calculations.md @@ -0,0 +1,110 @@ +--- +title: Use multiple fields in a calculation +description: > + Query multiple fields, pivot results, and use multiple field values to + calculate new values in query results. +influxdb/v2.1/tags: [queries] +menu: + influxdb_2_1: + parent: Common queries +weight: 103 +--- + +To use values from multiple fields in a mathematic calculation, complete the following steps: + +1. [Filter by fields required in your calculation](#filter-by-fields) +2. [Pivot fields into columns](#pivot-fields-into-columns) +3. [Perform the mathematic calculation](#perform-the-calculation) + +## Filter by fields +Use [`filter()`](/{{< latest "flux" >}}/stdlib/universe/filter/) +to return only the fields necessary for your calculation. +Use the [`or` logical operator](/{{< latest "flux" >}}/spec/operators/#logical-operators) +to filter by multiple fields. + +The following example queries two fields, `A` and `B`: + +```js +from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._field == "A" or r._field == "B") +``` + +This query returns one or more tables for each field. For example: + +{{< flex >}} +{{% flex-content %}} +| _time | _field | _value | +|:----- |:------:| ------:| +| 2021-01-01T00:00:00Z | A | 12.4 | +| 2021-01-01T00:00:15Z | A | 12.2 | +| 2021-01-01T00:00:30Z | A | 11.6 | +| 2021-01-01T00:00:45Z | A | 11.9 | +{{% /flex-content %}} +{{% flex-content %}} +| _time | _field | _value | +|:----- |:------:| ------:| +| 2021-01-01T00:00:00Z | B | 3.1 | +| 2021-01-01T00:00:15Z | B | 4.8 | +| 2021-01-01T00:00:30Z | B | 2.2 | +| 2021-01-01T00:00:45Z | B | 3.3 | +{{% /flex-content %}} +{{< /flex >}} + +## Pivot fields into columns +Use [`pivot()`](/{{< latest "flux" >}}/stdlib/universe/pivot/) +to align multiple fields by time. + +{{% note %}} +To correctly pivot on `_time`, points for each field must have identical timestamps. +If timestamps are irregular or do not align perfectly, see +[Normalize irregular timestamps](/influxdb/v2.1/query-data/flux/manipulate-timestamps/#normalize-irregular-timestamps). +{{% /note %}} + +```js +// ... + |> pivot( + rowKey:["_time"], + columnKey: ["_field"], + valueColumn: "_value" + ) +``` + +Using the queried data [above](#filter-by-fields), this `pivot()` function returns: + +| _time | A | B | +|:----- | ------:| ------:| +| 2021-01-01T00:00:00Z | 12.4 | 3.1 | +| 2021-01-01T00:00:15Z | 12.2 | 4.8 | +| 2021-01-01T00:00:30Z | 11.6 | 2.2 | +| 2021-01-01T00:00:45Z | 11.9 | 3.3 | + +## Perform the calculation +Use [`map()`](/{{< latest "flux" >}}/stdlib/universe/map/) +to perform the mathematic operation using column values as operands. + +The following example uses values in the `A` and `B` columns to calculate a new `_value` column: + +```js +// ... + |> map(fn: (r) => ({ r with _value: r.A * r.B })) +``` + +Using the pivoted data above, this `map()` function returns: + +| _time | A | B | _value | +|:----- | ------:| ------:| ------:| +| 2021-01-01T00:00:00Z | 12.4 | 3.1 | 38.44 | +| 2021-01-01T00:00:15Z | 12.2 | 4.8 | 58.56 | +| 2021-01-01T00:00:30Z | 11.6 | 2.2 | 25.52 | +| 2021-01-01T00:00:45Z | 11.9 | 3.3 | 39.27 | + +## Full example query + +```js +from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._field == "A" or r._field == "B") + |> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") + |> map(fn: (r) => ({ r with _value: r.A * r.B })) +``` diff --git a/content/influxdb/v2.1/query-data/common-queries/operate-on-columns.md b/content/influxdb/v2.1/query-data/common-queries/operate-on-columns.md new file mode 100644 index 0000000000..9c24c17456 --- /dev/null +++ b/content/influxdb/v2.1/query-data/common-queries/operate-on-columns.md @@ -0,0 +1,140 @@ +--- +title: Operate on columns +description: > + Find and count unique values, recalculate the `_value` column, and use values to calculate a new column. +influxdb/v2.1/tags: [queries] +aliases: + - /influxdb/v2.1/query-data/common-queries/count_unique_values_for_column/ + - /influxdb/v2.1/query-data/common-queries/recalculate_value_column/ + - /influxdb/v2.1/query-data/common-queries/calculate_new_column/ +menu: + influxdb_2_1: + name: Operate on columns + parent: Common queries +weight: 100 +--- + +Use the following common queries to operate on columns: + +- [Find and count unique values in a column](#find-and-count-unique-values-in-a-column) +- [Recalculate the _values column](#recalculate-the-_values-column) +- [Calculate a new column](#calculate-a-new-column) + +{{% note %}} +These examples use [NOAA water sample data](/influxdb/v2.1/reference/sample-data/#noaa-water-sample-data). +{{% /note %}} + +## Find and count unique values in a column + +Find and count the number of unique values in a specified column. +The following examples find and count unique locations where data was collected. + +### Find unique values + +This query: + + - Uses [`group()`](/{{< latest "flux" >}}/stdlib/universe/group/) to ungroup data and return results in a single table. + - Uses [`keep()`](/{{< latest "flux" >}}/stdlib/universe/keep/) and [`unique()`](/{{< latest "flux" >}}/stdlib/universe/selectors/unique/) to return unique values in the specified column. + +```js +from(bucket: "noaa") + |> range(start: -30d) + |> group() + |> keep(columns: ["location"]) + |> unique(column: "location") +``` + +#### Example results +| location | +|:-------- | +| coyote_creek | +| santa_monica | + +### Count unique values + +This query: + +- Uses [`group()`](/{{< latest "flux" >}}/stdlib/universe/group/) to ungroup data and return results in a single table. +- Uses [`keep()`](/{{< latest "flux" >}}/stdlib/universe/keep/), [`unique()`](/{{< latest "flux" >}}/stdlib/universe/unique/), and then [`count()`](/{{< latest "flux" >}}/stdlib/universe/count/) to count the number of unique values. + +```js +from(bucket: "noaa") + |> group() + |> unique(column: "location") + |> count(column: "location") +``` + +#### Example results + +| location | +| ---------:| +| 2 | + + +## Recalculate the _values column + +To recalculate the `_value` column, use the `with` operator in [`map()`](/{{< latest "flux" >}}/stdlib/universe/map/) to overwrite the existing `_value` column. + +The following query: + + - Uses [`filter()`](/{{< latest "flux" >}}/stdlib/universe/filter/) to filter the `average_temperature` measurement. + - Uses [`map()`](/{{< latest "flux" >}}/stdlib/universe/map/) to convert Fahrenheit temperature values into Celsius. + +```js + +from(bucket: "noaa") + |> filter(fn: (r) => r._measurement == "average_temperature") + |> range(start: -30d) + |> map(fn: (r) => ({r with _value: (float(v: r._value) - 32.0) * 5.0 / 9.0} )) +``` + +| _field | _measurement | _start | _stop | _time | location | _value | +|:------ |:------------ |:------ |:----- |:----- |:-------- | ------: | +| degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:00:00Z | coyote_creek | 27.77777777777778 | +| degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:06:00Z | coyote_creek | 22.77777777777778 | +| degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:12:00Z | coyote_creek | 30 | +| degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:18:00Z | coyote_creek | 31.666666666666668 | +| degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:24:00Z | coyote_creek | 25 | +| degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:30:00Z | coyote_creek | 21.11111111111111 | +| degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:36:00Z | coyote_creek | 28.88888888888889 | +| degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:42:00Z | coyote_creek | 24.444444444444443 | +| degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:48:00Z | coyote_creek | 29.444444444444443 | +| degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T00:54:00Z | coyote_creek | 26.666666666666668 | +| degrees | average_temperature | 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | 2019-08-17T01:00:00Z | coyote_creek | 21.11111111111111 | +| ••• | ••• | ••• | ••• | ••• | ••• | ••• | + +## Calculate a new column + +To use values in a row to calculate and add a new column, use `map()`. +This example below converts temperature from Fahrenheit to Celsius and maps the Celsius value to a new `celsius` column. + +The following query: + + - Uses [`filter()`](/{{< latest "flux" >}}/stdlib/universe/filter/) to filter the `average_temperature` measurement. + - Uses [`map()`](/{{< latest "flux" >}}/stdlib/universe/map/) to create a new column calculated from existing values in each row. + +```js +from(bucket: "noaa") + |> filter(fn: (r) => r._measurement == "average_temperature") + |> range(start: -30d) + |> map(fn: (r) => ({r with + celsius: ((r._value - 32.0) * 5.0 / 9.0) + }) + ) +``` + +#### Example results + +| _start | _stop | _field | _measurement | location | _time | _value | celsius | +|:------ |:----- |:------: |:------------: |:--------: |:----- | ------:| -------:| +| 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:00:00Z | 82 | 27.78 | +| 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:06:00Z | 73 | 22.78 | +| 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:12:00Z | 86 | 30.00 | +| 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:18:00Z | 89 | 31.67 | +| 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:24:00Z | 77 | 25.00 | +| 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:30:00Z | 70 | 21.11 | +| 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:36:00Z | 84 | 28.89 | +| 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:42:00Z | 76 | 24.44 | +| 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:48:00Z | 85 | 29.44 | +| 1920-03-05T22:10:01Z | 2020-03-05T22:10:01Z | degrees | average_temperature | coyote_creek | 2019-08-17T00:54:00Z | 80 | 26.67 | +| ••• | ••• | ••• | ••• | ••• | ••• | ••• | ••• | diff --git a/content/influxdb/v2.1/query-data/execute-queries/_index.md b/content/influxdb/v2.1/query-data/execute-queries/_index.md new file mode 100644 index 0000000000..e4aa650f83 --- /dev/null +++ b/content/influxdb/v2.1/query-data/execute-queries/_index.md @@ -0,0 +1,17 @@ +--- +title: Execute queries +seotitle: Different ways to query InfluxDB +description: There are multiple ways to query data from InfluxDB including the InfluxDB UI, CLI, and API. +weight: 103 +menu: + influxdb_2_1: + name: Execute queries + parent: Query data +influxdb/v2.1/tags: [query] +--- + +There are multiple ways to execute queries with InfluxDB. Choose from the following options: + +{{< children >}} + + diff --git a/content/influxdb/v2.1/query-data/execute-queries/data-explorer.md b/content/influxdb/v2.1/query-data/execute-queries/data-explorer.md new file mode 100644 index 0000000000..32c5e8e286 --- /dev/null +++ b/content/influxdb/v2.1/query-data/execute-queries/data-explorer.md @@ -0,0 +1,101 @@ +--- +title: Query in Data Explorer +description: > + Query InfluxDB using the InfluxDB user interface (UI) Data Explorer. Discover how to query data in InfluxDB 2.1 using the InfluxDB UI. +aliases: + - /influxdb/v2.1/visualize-data/explore-metrics/ +weight: 201 +menu: + influxdb_2_1: + name: Query with Data Explorer + parent: Execute queries +influxdb/v2.1/tags: [query] +--- + +Build, execute, and visualize your queries in InfluxDB UI's **Data Explorer**. + +![Data Explorer with Flux](/img/influxdb/2-0-data-explorer.png) + +Move seamlessly between using the Flux builder or templates and manually editing the query. +Choose between [visualization types](/influxdb/v2.1/visualize-data/visualization-types/) for your query. + +## Query data with Flux and the Data Explorer + +Flux is a functional data scripting language designed for querying, +analyzing, and acting on time series data. +See [Get started with Flux](/influxdb/v2.1/query-data/get-started) to learn more about Flux. + +1. In the navigation menu on the left, select **Explore** (**Data Explorer**). + + {{< nav-icon "data-explorer" >}} + +2. Use the Flux builder in the bottom panel to create a Flux query: + - Select a bucket to define your data source or select `+ Create Bucket` to add a new bucket. + - Edit your time range with the [time range option](#select-time-range) in the dropdown menu. + - Add filters to narrow your data by selecting attributes or columns in the dropdown menu. + - Select **Group** from the **Filter** dropdown menu to group data into tables. For more about how grouping data in Flux works, see [Group data](/influxdb/v2.1/query-data/flux/group-data/). +3. Alternatively, click **Script Editor** to manually edit the query. + To switch back to the query builder, click **Query Builder**. Note that your updates from the Script Editor will not be saved. +4. Use the **Functions** list to review the available Flux functions. + Click a function from the list to add it to your query. +5. Click **Submit** (or press `Control+Enter`) to run your query. You can then preview your graph in the above pane. + To cancel your query while it's running, click **Cancel**. +6. To work on multiple queries at once, click the {{< icon "plus" >}} to add another tab. + * Click the eye icon on a tab to hide or show a query's visualization. + * Click the name of the query in the tab to rename it. + +## Visualize your query + +- Select an available [visualization types](/influxdb/v2.1/visualize-data/visualization-types/) from the dropdown menu in the upper-left: + + {{< img-hd src="/img/influxdb/2-0-visualizations-dropdown.png" title="Visualization dropdown" />}} + +## Control your dashboard cell + +To open the cell editor overlay, click the gear icon in the upper right of a cell and select **Configure**. + The cell editor overlay opens. + +### View raw data + +Toggle the **View Raw Data** {{< icon "toggle" >}} option to see your data in table format instead of a graph. Scroll through raw data using arrows, or click page numbers to find specific tables. [Group keys](/influxdb/cloud/reference/glossary/#group-key) and [data types](/influxdb/cloud/reference/glossary/#data-type) are easily identifiable at the top of each column underneath the headings. Use this option when data can't be visualized using a visualization type. + + {{< img-hd src="/img/influxdb/cloud-controls-view-raw-data.png" alt="View raw data" />}} + +### Save as CSV + +Click the CSV icon to save the cells contents as a CSV file. + +### Manually refresh dashboard + +Click the refresh button ({{< icon "refresh" >}}) to manually refresh the dashboard's data. + +### Select time range + +1. Select from the time range options in the dropdown menu. + + {{< img-hd src="/img/influxdb/2-0-controls-time-range.png" alt="Select time range" />}} + +2. Select **Custom Time Range** to enter a custom time range with precision up to nanoseconds. +The default time range is 5m. + +> The custom time range uses the selected timezone (local time or UTC). + +### Query Builder or Script Editor + +Click **Query Builder** to use the builder to create a Flux query. Click **Script Editor** to manually edit the query. + +#### Keyboard shortcuts + +In **Script Editor** mode, the following keyboard shortcuts are available: + +| Key | Description | +|--------------------------------|---------------------------------------------| +| `Control + /` (`⌘ + /` on Mac) | Comment/uncomment current or selected lines | +| `Control + Enter` | Submit query | + +## Save your query as a dashboard cell or task + +- Click **Save as** in the upper right, and then: + - To add your query to a dashboard, click **Dashboard Cell**. + - To save your query as a task, click **Task**. + - To save your query as a variable, click **Variable**. diff --git a/content/influxdb/v2.1/query-data/execute-queries/flux-repl.md b/content/influxdb/v2.1/query-data/execute-queries/flux-repl.md new file mode 100644 index 0000000000..f5c757927f --- /dev/null +++ b/content/influxdb/v2.1/query-data/execute-queries/flux-repl.md @@ -0,0 +1,19 @@ +--- +title: Query in the Flux REPL +description: Query InfluxDB using the Flux REPL. Discover how to query data in InfluxDB 2.1 using the Flux REPL. +weight: 203 +menu: + influxdb_2_1: + name: Query in the Flux REPL + parent: Execute queries +influxdb/v2.1/tags: [query] +--- + +The [Flux REPL](/influxdb/v2.1/tools/repl/) starts an interactive +Read-Eval-Print Loop (REPL) where you can write and execute Flux queries. + +```sh +./flux repl +``` + +For more information, see [Use the Flux REPL](/influxdb/v2.1/tools/repl/). diff --git a/content/influxdb/v2.1/query-data/execute-queries/influx-api.md b/content/influxdb/v2.1/query-data/execute-queries/influx-api.md new file mode 100644 index 0000000000..50338e902d --- /dev/null +++ b/content/influxdb/v2.1/query-data/execute-queries/influx-api.md @@ -0,0 +1,105 @@ +--- +title: Query with the InfluxDB API +description: Query InfluxDB with the InfluxDB API. Discover how to query data in InfluxDB 2.1 using the InfluxDB API. +weight: 202 +menu: + influxdb_2_1: + name: Query with the InfluxDB API + parent: Execute queries +influxdb/v2.1/tags: [query] +--- + +The [InfluxDB v2 API](/influxdb/v2.1/reference/api) provides a programmatic interface for all interactions with InfluxDB. +To query InfluxDB {{< current-version >}}, do one of the following: + +- Send a Flux query request to the [`/api/v2/query`](/influxdb/v2.1/api/#operation/PostQueryAnalyze) endpoint. +- Send an InfluxQL query request to the [/query 1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/query/). + +In your request, set the following: + +- Your organization via the `org` or `orgID` URL parameters. +- `Authorization` header to `Token ` + your API token. +- `Accept` header to `application/csv`. +- `Content-type` header to `application/vnd.flux` (Flux only) or `application/json` (Flux or InfluxQL). +- Query in Flux or InfluxQL with the request's raw data. + +{{% note %}} +#### Use gzip to compress the query response + +To compress the query response, set the `Accept-Encoding` header to `gzip`. +This saves network bandwidth, but increases server-side load. +{{% /note %}} + +#### Flux - Example query request + +Below is an example `curl` request that sends a Flux query to InfluxDB {{< current-version >}}: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Without compression](#) +[With compression](#) +{{% /code-tabs %}} + +{{% code-tab-content %}} +```bash +curl --request POST \ + http://localhost:8086/api/v2/query?org=my-org \ + --header 'Authorization: Token YOURAUTHTOKEN' \ + --header 'Accept: application/csv' \ + --header 'Content-type: application/vnd.flux' \ + --data 'from(bucket:"example-bucket") + |> range(start: -12h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> aggregateWindow(every: 1h, fn: mean)' +``` +{{% /code-tab-content %}} + +{{% code-tab-content %}} +```bash +curl --request POST \ + http://localhost:8086/api/v2/query?org=my-org \ + --header 'Authorization: Token YOURAUTHTOKEN' \ + --header 'Accept: application/csv' \ + --header 'Content-type: application/vnd.flux' \ + --header 'Accept-Encoding: gzip' \ + --data 'from(bucket:"example-bucket") + |> range(start: -12h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> aggregateWindow(every: 1h, fn: mean)' +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +#### InfluxQL - Example query request + +Below is an example `curl` request that sends an InfluxQL query to InfluxDB {{< current-version >}}: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Without compression](#) +[With compression](#) +{{% /code-tabs %}} + +{{% code-tab-content %}} +```bash +curl --request -G http://localhost:8086/query?org=my-org?database=MyDB&retention_policy=MyRP \ + --header 'Authorization: Token YOURAUTHTOKEN' \ + --header 'Accept: application/csv' \ + --header 'Content-type: application/json' \ + --data-urlencode "q=SELECT used_percent FROM example-db.example-rp.example-measurement WHERE host=host1" +``` +{{% /code-tab-content %}} + +{{% code-tab-content %}} +```bash +curl --request -G http://localhost:8086/query?org=my-org?database=MyDB&retention_policy=MyRP \ + --header 'Authorization: Token YOURAUTHTOKEN' \ + --header 'Accept: application/csv' \ + --header 'Content-type: application/json' \ + --header 'Accept-Encoding: gzip' \ + --data-urlencode "q=SELECT used_percent FROM example-db.example-rp.example-measurement WHERE host=host1" +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +InfluxDB returns the query results in [annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv/). diff --git a/content/influxdb/v2.1/query-data/execute-queries/influx-query.md b/content/influxdb/v2.1/query-data/execute-queries/influx-query.md new file mode 100644 index 0000000000..c3b1da39be --- /dev/null +++ b/content/influxdb/v2.1/query-data/execute-queries/influx-query.md @@ -0,0 +1,41 @@ +--- +title: Use the influx query command +description: Query InfluxDB using the influx CLI. Discover how to query data in InfluxDB 2.1 using `influx query`. +weight: 204 +menu: + influxdb_2_1: + name: Use the influx CLI + parent: Execute queries +influxdb/v2.1/tags: [query] +related: + - /influxdb/v2.1/reference/cli/influx/query/ +--- + +Use the [`influx query` command](/influxdb/v2.1/reference/cli/influx/query) to query data in InfluxDB using Flux. +Pass Flux queries to the command as either a file or via stdin. + +###### Run a query from a file + +```bash +influx query --file /path/to/query.flux +``` + +###### Pass raw Flux via stdin pipe + +```bash +influx query - # Return to open the pipe + +data = from(bucket: "example-bucket") |> range(start: -10m) # ... +# ctrl-d to close the pipe and submit the query +``` + +{{% note %}} +#### Remove unnecessary columns in large datasets +When using the `influx query` command to query and download large datasets, +drop columns such as `_start` and `_stop` to optimize the download file size. + +```js +// ... + |> drop(columns: ["_start", "_stop"]) +``` +{{% /note %}} diff --git a/content/influxdb/v2.1/query-data/execute-queries/query-sample-data.md b/content/influxdb/v2.1/query-data/execute-queries/query-sample-data.md new file mode 100644 index 0000000000..91f9ae9c1a --- /dev/null +++ b/content/influxdb/v2.1/query-data/execute-queries/query-sample-data.md @@ -0,0 +1,89 @@ +--- +title: Query sample data +description: > + Explore InfluxDB OSS with our sample data buckets. +menu: + influxdb_2_1:: + name: Query with sample data + parent: Execute queries +weight: 10 +--- + +Use **InfluxDB OSS** sample datasets to quickly access data that lets you explore and familiarize yourself with InfluxDB Cloud without requiring you to have or write your own data. + +- [Choose sample data](#choose-sample-data) +- [Explore sample data](#explore-sample-data) +- [Create sample data dashboards](#create-sample-data-dashboards) + +{{% note %}} +#### Network bandwidth + +Each execution of `sample.data()` downloads the specified dataset from **Amazon S3**. +If using [InfluxDB Cloud](/influxdb/cloud/) or a hosted InfluxDB OSS instance, +you may see additional network bandwidth costs when using this function. +Approximate sample dataset sizes are listed for each [sample dataset](/influxdb/v2.1/reference/sample-data/#sample-datasets) and in the output of [`sample.list()`](/influxdb/v2.1/reference/flux/stdlib/influxdb-sample/list/). + +If you also want to explore Cloud, we offer a way to explore data without incurring network bandwidth costs, using [demo data](/influxdb/cloud/query-data/execute-queries/query-demo-data/). +{{% /note %}} + +## Choose sample data + +1. Choose from the following sample datasets: + - **Air sensor sample data**: Explore, visualize, and monitor humidity, temperature, and carbon monoxide levels in the air. + - **Bird migration sample data**: Explore, visualize, and monitor the latitude and longitude of bird migration patterns. + - **NOAA NDBC sample data**: Explore, visualize, and monitor NDBC's observations from their buoys. This data observes air temperature, wind speed, and more from specific locations. + - **NOAA water sample data**: Explore, visualize, and monitor temperature, water level, pH, and quality from specific locations. + - **USGS Earthquake data**: Explore, visualize, and monitor earthquake monitoring data. This data includes alerts, cdi, quarry blast, magnitide, and more. +2. Do one of the following to download sample data: + - [Add sample data with community template](#add-sample-data-with-community-templates) + - [Add sample data using the InfluxDB UI](#add-sample-data) + +### Add sample data with community template + +1. Visit the **InfluxDB templates page** in the InfluxDB OSS UI. Click **Settings** > **Templates** in the navigation menu on the left. + + {{< nav-icon "settings" >}} + +2. Paste the Sample Data community temple URL in **resource manifest file** field: + + ``` + https://github.com/influxdata/community-templates/blob/master/sample-data/sample-data.yml + ``` + +## Explore sample data +Use the [Data Explorer](/influxdb/cloud/visualize-data/explore-metrics/) +to query and visualize data in sample data buckets. + +In the navigation menu on the left, click **Explore (Data Explorer)**. + +{{< nav-icon "explore" >}} + +### Add sample data + +1. In the navigation menu on the left, click **Data (Load Data)** > **Buckets**. + + {{< nav-icon "data" >}} + +2. Click **{{< icon "plus" >}} Create bucket**, and then name your bucket. The bucket will appear in your list of buckets. +3. View the [sample datasets document](/influxdb/cloud/reference/sample-data/#sample-datasets) and choose a sample data to query. +4. Copy the `sample.data()` function listed underneath. +5. Click **Explore** on the left navigation of InfluxDB Cloud and click your bucket, and then click **Script Editor**. +6. Paste the `sample.data()` function. +7. Click **Submit** to run the query. + +For more information about querying in the Script Editor, see how to [Query data with Flux and the Data Explorer](/influxdb/cloud/query-data/execute-queries/data-explorer/#query-data-with-flux-and-the-data-explorer). + +## Create sample data dashboards + +After adding a sample data bucket, create a dashboard specific to the sample dataset: + +1. Click **Boards (Dashboards)** in the navigation menu on the left. + + {{< nav-icon "dashboards" >}} + +2. Click **Create Dashboard > New Dashboard**, and name the dashboard after your bucket. +3. Click **Add Cell**, and select your sample data bucket. +4. Click **Script Editor**. +5. Copy and paste the `sample.data()` function into the script editor. +6. Click **Submit** to run the query. +6. Define the variables of your sample data. diff --git a/content/influxdb/v2.1/query-data/flux/_index.md b/content/influxdb/v2.1/query-data/flux/_index.md new file mode 100644 index 0000000000..c640d26f5a --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/_index.md @@ -0,0 +1,38 @@ +--- +title: Query data with Flux +description: Guides that walk through both common and complex queries and use cases for Flux. +weight: 102 +influxdb/v2.1/tags: [flux, query] +menu: + influxdb_2_1: + name: Query with Flux + parent: Query data +alias: + - /influxdb/v2.1/query-data/guides/ +--- + +The following guides walk through both common and complex queries and use cases for Flux. + +{{% note %}} +#### Example data variable +Many of the examples provided in the following guides use a `data` variable, +which represents a basic query that filters data by measurement and field. +`data` is defined as: + +```js +data = from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "example-measurement" and + r._field == "example-field" + ) +``` +{{% /note %}} + +## Flux query guides + +{{< children type="anchored-list" pages="all" >}} + +--- + +{{< children pages="all" readmore=true hr=true >}} diff --git a/content/influxdb/v2.1/query-data/flux/calculate-percentages.md b/content/influxdb/v2.1/query-data/flux/calculate-percentages.md new file mode 100644 index 0000000000..ed380beea1 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/calculate-percentages.md @@ -0,0 +1,215 @@ +--- +title: Calculate percentages with Flux +list_title: Calculate percentages +description: > + Use [`pivot()` or `join()`](/influxdb/v2.1/query-data/flux/mathematic-operations/#pivot-vs-join) + and the `map()` function to align operand values into rows and calculate a percentage. +menu: + influxdb_2_1: + name: Calculate percentages + parent: Query with Flux +weight: 209 +aliases: + - /influxdb/v2.1/query-data/guides/calculate-percentages/ +related: + - /influxdb/v2.1/query-data/flux/mathematic-operations + - /{{< latest "flux" >}}/stdlib/universe/map + - /{{< latest "flux" >}}/stdlib/universe/pivot + - /{{< latest "flux" >}}/stdlib/universe/join +list_query_example: percentages +--- + +Calculating percentages from queried data is a common use case for time series data. +To calculate a percentage in Flux, operands must be in each row. +Use `map()` to re-map values in the row and calculate a percentage. + +**To calculate percentages** + +1. Use [`from()`](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/from/), + [`range()`](/{{< latest "flux" >}}/stdlib/universe/range/) and + [`filter()`](/{{< latest "flux" >}}/stdlib/universe/filter/) to query operands. +2. Use [`pivot()` or `join()`](/influxdb/v2.1/query-data/flux/mathematic-operations/#pivot-vs-join) + to align operand values into rows. +3. Use [`map()`](/{{< latest "flux" >}}/stdlib/universe/map/) + to divide the numerator operand value by the denominator operand value and multiply by 100. + +{{% note %}} +The following examples use `pivot()` to align operands into rows because +`pivot()` works in most cases and is more performant than `join()`. +_See [Pivot vs join](/influxdb/v2.1/query-data/flux/mathematic-operations/#pivot-vs-join)._ +{{% /note %}} + +```js +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "m1" and r._field =~ /field[1-2]/ ) + |> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") + |> map(fn: (r) => ({ r with _value: r.field1 / r.field2 * 100.0 })) +``` + +## GPU monitoring example +The following example queries data from the gpu-monitor bucket and calculates the +percentage of GPU memory used over time. +Data includes the following: + +- **`gpu` measurement** +- **`mem_used` field**: used GPU memory in bytes +- **`mem_total` field**: total GPU memory in bytes + +### Query mem_used and mem_total fields +```js +from(bucket: "gpu-monitor") + |> range(start: 2020-01-01T00:00:00Z) + |> filter(fn: (r) => r._measurement == "gpu" and r._field =~ /mem_/) +``` + +###### Returns the following stream of tables: + +| _time | _measurement | _field | _value | +|:----- |:------------:|:------: | ------: | +| 2020-01-01T00:00:00Z | gpu | mem_used | 2517924577 | +| 2020-01-01T00:00:10Z | gpu | mem_used | 2695091978 | +| 2020-01-01T00:00:20Z | gpu | mem_used | 2576980377 | +| 2020-01-01T00:00:30Z | gpu | mem_used | 3006477107 | +| 2020-01-01T00:00:40Z | gpu | mem_used | 3543348019 | +| 2020-01-01T00:00:50Z | gpu | mem_used | 4402341478 | + +

    + +| _time | _measurement | _field | _value | +|:----- |:------------:|:------: | ------: | +| 2020-01-01T00:00:00Z | gpu | mem_total | 8589934592 | +| 2020-01-01T00:00:10Z | gpu | mem_total | 8589934592 | +| 2020-01-01T00:00:20Z | gpu | mem_total | 8589934592 | +| 2020-01-01T00:00:30Z | gpu | mem_total | 8589934592 | +| 2020-01-01T00:00:40Z | gpu | mem_total | 8589934592 | +| 2020-01-01T00:00:50Z | gpu | mem_total | 8589934592 | + +### Pivot fields into columns +Use `pivot()` to pivot the `mem_used` and `mem_total` fields into columns. +Output includes `mem_used` and `mem_total` columns with values for each corresponding `_time`. + +```js +// ... + |> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") +``` + +###### Returns the following: + +| _time | _measurement | mem_used | mem_total | +|:----- |:------------:| --------: | ---------: | +| 2020-01-01T00:00:00Z | gpu | 2517924577 | 8589934592 | +| 2020-01-01T00:00:10Z | gpu | 2695091978 | 8589934592 | +| 2020-01-01T00:00:20Z | gpu | 2576980377 | 8589934592 | +| 2020-01-01T00:00:30Z | gpu | 3006477107 | 8589934592 | +| 2020-01-01T00:00:40Z | gpu | 3543348019 | 8589934592 | +| 2020-01-01T00:00:50Z | gpu | 4402341478 | 8589934592 | + +### Map new values +Each row now contains the values necessary to calculate a percentage. +Use `map()` to re-map values in each row. +Divide `mem_used` by `mem_total` and multiply by 100 to return the percentage. + +{{% note %}} +To return a precise float percentage value that includes decimal points, the example +below casts integer field values to floats and multiplies by a float value (`100.0`). +{{% /note %}} + +```js +// ... + |> map(fn: (r) => ({ + _time: r._time, + _measurement: r._measurement, + _field: "mem_used_percent", + _value: float(v: r.mem_used) / float(v: r.mem_total) * 100.0 + })) +``` +##### Query results: + +| _time | _measurement | _field | _value | +|:----- |:------------:|:------: | ------: | +| 2020-01-01T00:00:00Z | gpu | mem_used_percent | 29.31 | +| 2020-01-01T00:00:10Z | gpu | mem_used_percent | 31.37 | +| 2020-01-01T00:00:20Z | gpu | mem_used_percent | 30.00 | +| 2020-01-01T00:00:30Z | gpu | mem_used_percent | 35.00 | +| 2020-01-01T00:00:40Z | gpu | mem_used_percent | 41.25 | +| 2020-01-01T00:00:50Z | gpu | mem_used_percent | 51.25 | + +### Full query +```js +from(bucket: "gpu-monitor") + |> range(start: 2020-01-01T00:00:00Z) + |> filter(fn: (r) => r._measurement == "gpu" and r._field =~ /mem_/ ) + |> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") + |> map(fn: (r) => ({ + _time: r._time, + _measurement: r._measurement, + _field: "mem_used_percent", + _value: float(v: r.mem_used) / float(v: r.mem_total) * 100.0 + })) +``` + +## Examples + +#### Calculate percentages using multiple fields +```js +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> filter(fn: (r) => + r._field == "used_system" or + r._field == "used_user" or + r._field == "total" + ) + |> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") + |> map(fn: (r) => ({ r with + _value: float(v: r.used_system + r.used_user) / float(v: r.total) * 100.0 + })) +``` + +#### Calculate percentages using multiple measurements + +1. Ensure measurements are in the same [bucket](/influxdb/v2.1/reference/glossary/#bucket). +2. Use `filter()` to include data from both measurements. +3. Use `group()` to ungroup data and return a single table. +4. Use `pivot()` to pivot fields into columns. +5. Use `map()` to re-map rows and perform the percentage calculation. + + +```js +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + (r._measurement == "m1" or r._measurement == "m2") and + (r._field == "field1" or r._field == "field2") + ) + |> group() + |> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") + |> map(fn: (r) => ({ r with _value: r.field1 / r.field2 * 100.0 })) +``` + +#### Calculate percentages using multiple data sources +```js +import "sql" +import "influxdata/influxdb/secrets" + +pgUser = secrets.get(key: "POSTGRES_USER") +pgPass = secrets.get(key: "POSTGRES_PASSWORD") +pgHost = secrets.get(key: "POSTGRES_HOST") + +t1 = sql.from( + driverName: "postgres", + dataSourceName: "postgresql://${pgUser}:${pgPass}@${pgHost}", + query:"SELECT id, name, available FROM example_table" +) + +t2 = from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "example-measurement" and + r._field == "example-field" + ) + +join(tables: {t1: t1, t2: t2}, on: ["id"]) + |> map(fn: (r) => ({ r with _value: r._value_t2 / r.available_t1 * 100.0 })) +``` diff --git a/content/influxdb/v2.1/query-data/flux/conditional-logic.md b/content/influxdb/v2.1/query-data/flux/conditional-logic.md new file mode 100644 index 0000000000..691cdd3733 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/conditional-logic.md @@ -0,0 +1,208 @@ +--- +title: Query using conditional logic +seotitle: Query using conditional logic in Flux +list_title: Conditional logic +description: > + This guide describes how to use Flux conditional expressions, such as `if`, + `else`, and `then`, to query and transform data. **Flux evaluates statements from left to right and stops evaluating once a condition matches.** +influxdb/v2.1/tags: [conditionals, flux] +menu: + influxdb_2_1: + name: Conditional logic + parent: Query with Flux +weight: 220 +aliases: + - /influxdb/v2.1/query-data/guides/conditional-logic/ +related: + - /influxdb/v2.1/query-data/flux/query-fields/ + - /{{< latest "flux" >}}/stdlib/universe/filter/ + - /{{< latest "flux" >}}/stdlib/universe/map/ + - /{{< latest "flux" >}}/stdlib/universe/reduce/ +list_code_example: | + ```js + if color == "green" then "008000" else "ffffff" + ``` +--- + +Flux provides `if`, `then`, and `else` conditional expressions that allow for powerful and flexible Flux queries. + +If you're just getting started with Flux queries, check out the following: + +- [Get started with Flux](/{{< latest "flux" >}}/get-started/) for a conceptual overview of Flux and parts of a Flux query. +- [Execute queries](/influxdb/v2.1/query-data/execute-queries/) to discover a variety of ways to run your queries. + +##### Conditional expression syntax +```js +// Pattern +if then else + +// Example +if color == "green" then "008000" else "ffffff" +``` + +Conditional expressions are most useful in the following contexts: + +- When defining variables. +- When using functions that operate on a single row at a time ( + [`filter()`](/{{< latest "flux" >}}/stdlib/universe/filter/), + [`map()`](/{{< latest "flux" >}}/stdlib/universe/map/), + [`reduce()`](/{{< latest "flux" >}}/stdlib/universe/reduce) ). + +## Evaluating conditional expressions + +Flux evaluates statements in order and stops evaluating once a condition matches. + +For example, given the following statement: + +```js +if r._value > 95.0000001 and r._value <= 100.0 then "critical" +else if r._value > 85.0000001 and r._value <= 95.0 then "warning" +else if r._value > 70.0000001 and r._value <= 85.0 then "high" +else "normal" +``` + +When `r._value` is 96, the output is "critical" and the remaining conditions are not evaluated. + +## Examples + +- [Conditionally set the value of a variable](#conditionally-set-the-value-of-a-variable) +- [Create conditional filters](#create-conditional-filters) +- [Conditionally transform column values with map()](#conditionally-transform-column-values-with-map) +- [Conditionally increment a count with reduce()](#conditionally-increment-a-count-with-reduce) + +### Conditionally set the value of a variable +The following example sets the `overdue` variable based on the +`dueDate` variable's relation to `now()`. + +```js +dueDate = 2019-05-01 +overdue = if dueDate < now() then true else false +``` + +### Create conditional filters +The following example uses an example `metric` [dashboard variable](/influxdb/v2.1/visualize-data/variables/) +to change how the query filters data. +`metric` has three possible values: + +- Memory +- CPU +- Disk + +```js +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + if v.metric == "Memory" + then r._measurement == "mem" and r._field == "used_percent" + else if v.metric == "CPU" + then r._measurement == "cpu" and r._field == "usage_user" + else if v.metric == "Disk" + then r._measurement == "disk" and r._field == "used_percent" + else r._measurement != "" + ) +``` + + +### Conditionally transform column values with map() +The following example uses the [`map()` function](/{{< latest "flux" >}}/stdlib/universe/map/) +to conditionally transform column values. +It sets the `level` column to a specific string based on `_value` column. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[No Comments](#) +[Comments](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent" ) + |> map(fn: (r) => ({ + r with + level: + if r._value >= 95.0000001 and r._value <= 100.0 then "critical" + else if r._value >= 85.0000001 and r._value <= 95.0 then "warning" + else if r._value >= 70.0000001 and r._value <= 85.0 then "high" + else "normal" + }) + ) +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent" ) + |> map(fn: (r) => ({ + // Retain all existing columns in the mapped row + r with + // Set the level column value based on the _value column + level: + if r._value >= 95.0000001 and r._value <= 100.0 then "critical" + else if r._value >= 85.0000001 and r._value <= 95.0 then "warning" + else if r._value >= 70.0000001 and r._value <= 85.0 then "high" + else "normal" + }) + ) +``` + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +### Conditionally increment a count with reduce() +The following example uses the [`aggregateWindow()`](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow/) +and [`reduce()`](/{{< latest "flux" >}}/stdlib/universe/reduce/) +functions to count the number of records in every five minute window that exceed a defined threshold. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[No Comments](#) +[Comments](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```js +threshold = 65.0 + +data = from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent" ) + |> aggregateWindow( + every: 5m, + fn: (column, tables=<-) => tables |> reduce( + identity: {above_threshold_count: 0.0}, + fn: (r, accumulator) => ({ + above_threshold_count: + if r._value >= threshold then accumulator.above_threshold_count + 1.0 + else accumulator.above_threshold_count + 0.0 + }) + ) + ) +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```js +threshold = 65.0 + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent" ) + // Aggregate data into 5 minute windows using a custom reduce() function + |> aggregateWindow( + every: 5m, + // Use a custom function in the fn parameter. + // The aggregateWindow fn parameter requires 'column' and 'tables' parameters. + fn: (column, tables=<-) => tables |> reduce( + identity: {above_threshold_count: 0.0}, + fn: (r, accumulator) => ({ + // Conditionally increment above_threshold_count if + // r.value exceeds the threshold + above_threshold_count: + if r._value >= threshold then accumulator.above_threshold_count + 1.0 + else accumulator.above_threshold_count + 0.0 + }) + ) + ) +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} diff --git a/content/influxdb/v2.1/query-data/flux/cumulativesum.md b/content/influxdb/v2.1/query-data/flux/cumulativesum.md new file mode 100644 index 0000000000..7d12c4d802 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/cumulativesum.md @@ -0,0 +1,70 @@ +--- +title: Query cumulative sum +seotitle: Query cumulative sum in Flux +list_title: Cumulative sum +description: > + Use the `cumulativeSum()` function to calculate a running total of values. +weight: 210 +menu: + influxdb_2_1: + parent: Query with Flux + name: Cumulative sum +influxdb/v2.1/tags: [query, cumulative sum] +related: + - /{{< latest "flux" >}}/stdlib/universe/cumulativesum/ +list_query_example: cumulative_sum +--- + +Use the [`cumulativeSum()` function](/{{< latest "flux" >}}/stdlib/universe/cumulativesum/) +to calculate a running total of values. +`cumulativeSum` sums the values of subsequent records and returns each row updated with the summed total. + +{{< flex >}} +{{% flex-content "half" %}} +**Given the following input table:** + +| _time | _value | +| ----- |:------:| +| 0001 | 1 | +| 0002 | 2 | +| 0003 | 1 | +| 0004 | 3 | +{{% /flex-content %}} +{{% flex-content "half" %}} +**`cumulativeSum()` returns:** + +| _time | _value | +| ----- |:------:| +| 0001 | 1 | +| 0002 | 3 | +| 0003 | 4 | +| 0004 | 7 | +{{% /flex-content %}} +{{< /flex >}} + +{{% note %}} +The examples below use the [example data variable](/influxdb/v2.1/query-data/flux/#example-data-variable). +{{% /note %}} + +##### Calculate the running total of values +```js +data + |> cumulativeSum() +``` + +## Use cumulativeSum() with aggregateWindow() +[`aggregateWindow()`](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow/) +segments data into windows of time, aggregates data in each window into a single +point, then removes the time-based segmentation. +It is primarily used to [downsample data](/influxdb/v2.1/process-data/common-tasks/downsample-data/). + +`aggregateWindow()` expects an aggregate function that returns a single row for each time window. +To use `cumulativeSum()` with `aggregateWindow`, use `sum` in `aggregateWindow()`, +then calculate the running total of the aggregate values with `cumulativeSum()`. + + +```js +data + |> aggregateWindow(every: 5m, fn: sum) + |> cumulativeSum() +``` diff --git a/content/influxdb/v2.1/query-data/flux/custom-functions/_index.md b/content/influxdb/v2.1/query-data/flux/custom-functions/_index.md new file mode 100644 index 0000000000..5457b63783 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/custom-functions/_index.md @@ -0,0 +1,226 @@ +--- +title: Create custom Flux functions +description: Create your own custom Flux functions to transform and operate on data. +list_title: Custom functions +influxdb/v2.1/tags: [functions, custom, flux] +menu: + influxdb_2_1: + name: Custom functions + parent: Query with Flux +weight: 220 +aliases: + - /influxdb/v2.1/query-data/guides/custom-functions/ +list_code_example: | + ```js + multByX = (tables=<-, x) => + tables + |> map(fn: (r) => ({ r with _value: r._value * x})) + + data + |> multByX(x: 2.0) + ``` +--- + +Flux's functional syntax lets you create custom functions. +This guide walks through the basics of creating your own function. + +- [Function definition syntax](#function-definition-syntax) +- [Use piped-forward data in a custom function](#use-piped-forward-data-in-a-custom-function) +- [Define parameter defaults](#define-parameter-defaults) +- [Define functions with scoped variables](#define-functions-with-scoped-variables) + +## Function definition syntax +The basic syntax for defining functions in Flux is as follows: + +```js +// Basic function definition syntax +functionName = (functionParameters) => functionOperations +``` + +##### functionName +The name used to call the function in your Flux script. + +##### functionParameters +A comma-separated list of parameters passed into the function and used in its operations. +[Parameter defaults](#define-parameter-defaults) can be defined for each. + +##### functionOperations +Operations and functions that manipulate the input into the desired output. + +#### Basic function examples + +###### Example square function +```js +// Function definition +square = (n) => n * n + +// Function usage +> square(n:3) +9 +``` + +###### Example multiply function +```js +// Function definition +multiply = (x, y) => x * y + +// Function usage +> multiply(x: 2, y: 15) +30 +``` + +## Use piped-forward data in a custom function +Most Flux functions process piped-forward data. +To process piped-forward data, one of the function +parameters must capture the input tables using the `<-` pipe-receive expression. + +In the example below, the `tables` parameter is assigned to the `<-` expression, +which represents all data piped-forward into the function. +`tables` is then piped-forward into other operations in the function definition. + +```js +functionName = (tables=<-) => tables |> functionOperations +``` + +#### Pipe-forwardable function example + +###### Multiply row values by x +The example below defines a `multByX` function that multiplies the `_value` column +of each row in the input table by the `x` parameter. +It uses the [`map()` function](/{{< latest "flux" >}}/stdlib/universe/map) +to modify each `_value`. + +```js +// Function definition +multByX = (tables=<-, x) => + tables + |> map(fn: (r) => ({ r with _value: r._value * x})) + +// Function usage +from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> multByX(x:2.0) +``` + +## Define parameter defaults +Use the `=` assignment operator to assign a default value to function parameters +in your function definition: + +```js +functionName = (param1=defaultValue1, param2=defaultValue2) => functionOperation +``` + +Defaults are overridden by explicitly defining the parameter in the function call. + +### Example functions with defaults + +#### Get a list of leaders +The example below defines a `leaderBoard` function that returns a limited number +of records sorted by values in specified columns. +It uses the [`sort()` function](/{{< latest "flux" >}}/stdlib/universe/sort) +to sort records in either descending or ascending order. +It then uses the [`limit()` function](/{{< latest "flux" >}}/stdlib/universe/limit) +to return a specified number of records from the sorted table. + +```js +// Function definition +leaderBoard = (tables=<-, limit=4, columns=["_value"], desc=true) => + tables + |> sort(columns: columns, desc: desc) + |> limit(n: limit) + +// Function usage +// Get the 4 highest scoring players +from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => + r._measurement == "player-stats" and + r._field == "total-points" + ) + |> leaderBoard() + +// Get the 10 shortest race times +from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => + r._measurement == "race-times" and + r._field == "elapsed-time" + ) + |> leaderBoard(limit: 10, desc: false) +``` + +## Define functions with scoped variables +To create custom functions with variables scoped to the function, place your +function operations and variables inside of a [block (`{}`)](/influxdb/v2.1/reference/flux/language/blocks/) +and use a `return` statement to return a specific variable. + +```js +functionName = (functionParameters) => { + exampleVar = "foo" + return exampleVar +} +``` + +### Example functions with scoped variables + +- [Return an alert level based on a value](#return-an-alert-level-based-on-a-value) +- [Convert a HEX color code to a name](#convert-a-hex-color-code-to-a-name) + +#### Return an alert level based on a value +The following function uses conditional logic to return an alert level based on +a numeric input value: + +```js +alertLevel = (v) => { + level = if float(v:v) >= 90.0 then "crit" + else if float(v:v) >= 80.0 then "warn" + else if float(v:v) >= 65.0 then "info" + else "ok" + return level +} + +alertLevel(v: 87.3) +// Returns "warn" +``` + +#### Convert a HEX color code to a name +The following function converts a hexadecimal (HEX) color code to the equivalent HTML color name. +The functions uses the [Flux dictionary package](/{{< latest "flux" >}}/stdlib/dict/) +to create a dictionary of HEX codes and their corresponding names. + +```js +import "dict" + +hexName = (hex) => { + hexNames = dict.fromList(pairs: [ + {key: "#00ffff", value: "Aqua"}, + {key: "#000000", value: "Black"}, + {key: "#0000ff", value: "Blue"}, + {key: "#ff00ff", value: "Fuchsia"}, + {key: "#808080", value: "Gray"}, + {key: "#008000", value: "Green"}, + {key: "#00ff00", value: "Lime"}, + {key: "#800000", value: "Maroon"}, + {key: "#000080", value: "Navy"}, + {key: "#808000", value: "Olive"}, + {key: "#800080", value: "Purple"}, + {key: "#ff0000", value: "Red"}, + {key: "#c0c0c0", value: "Silver"}, + {key: "#008080", value: "Teal"}, + {key: "#ffffff", value: "White"}, + {key: "#ffff00", value: "Yellow"}, + ]) + name = dict.get(dict: hexNames, key: hex, default: "No known name") + return name +} + +hexName(hex: "#000000") +// Returns "Black" + +hexName(hex: "#8b8b8b") +// Returns "No known name" +``` diff --git a/content/influxdb/v2.1/query-data/flux/custom-functions/custom-aggregate.md b/content/influxdb/v2.1/query-data/flux/custom-functions/custom-aggregate.md new file mode 100644 index 0000000000..b9de85ecc4 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/custom-functions/custom-aggregate.md @@ -0,0 +1,258 @@ +--- +title: Create custom aggregate functions +description: Create your own custom aggregate functions in Flux using the `reduce()` function. +influxdb/v2.1/tags: [functions, custom, flux, aggregates] +menu: + influxdb_2_1: + name: Custom aggregate functions + parent: Custom functions +weight: 301 +aliases: + - /influxdb/v2.1/query-data/guides/custom-functions/custom-aggregate/ +related: + - /i{{< latest "flux" >}}/stdlib/universe/reduce/ +--- + +To aggregate your data, use the Flux +[aggregate functions](/{{< latest "flux" >}}/function-types#aggregates) +or create custom aggregate functions using the +[`reduce()`function](/{{< latest "flux" >}}/stdlib/universe/reduce/). + +## Aggregate function characteristics +Aggregate functions all have the same basic characteristics: + +- They operate on individual input tables and transform all records into a single record. +- The output table has the same [group key](/{{< latest "flux" >}}/get-started/data-model/#group-key) as the input table. + +## How reduce() works +The `reduce()` function operates on one row at a time using the function defined in +the [`fn` parameter](/{{< latest "flux" >}}/stdlib/universe/reduce/#fn). +The `fn` function maps keys to specific values using two [records](/{{< latest "flux" >}}/data-types/composite/record/) +specified by the following parameters: + +| Parameter | Description | +|:---------: |:----------- | +| `r` | A record that represents the row or record. | +| `accumulator` | A record that contains values used in each row's aggregate calculation. | + +{{% note %}} +The `reduce()` function's [`identity` parameter](/{{< latest "flux" >}}/stdlib/universe/reduce/#identity) +defines the initial `accumulator` record. +{{% /note %}} + +### Example reduce() function +The following example `reduce()` function produces a sum and product of all values +in an input table. + +```js +|> reduce(fn: (r, accumulator) => ({ + sum: r._value + accumulator.sum, + product: r._value * accumulator.product + }), + identity: {sum: 0.0, product: 1.0} +) +``` + +To illustrate how this function works, take this simplified table for example: + +| _time | _value | +|:----- | ------:| +| 2019-04-23T16:10:49Z | 1.6 | +| 2019-04-23T16:10:59Z | 2.3 | +| 2019-04-23T16:11:09Z | 0.7 | +| 2019-04-23T16:11:19Z | 1.2 | +| 2019-04-23T16:11:29Z | 3.8 | + +###### Input records +The `fn` function uses the data in the first row to define the `r` record. +It defines the `accumulator` record using the `identity` parameter. + +```js +r = { _time: 2019-04-23T16:10:49.00Z, _value: 1.6 } +accumulator = { sum : 0.0, product : 1.0 } +``` + +###### Key mappings +It then uses the `r` and `accumulator` records to populate values in the key mappings: +```js +// sum: r._value + accumulator.sum +sum: 1.6 + 0.0 + +// product: r._value * accumulator.product +product: 1.6 * 1.0 +``` + +###### Output record +This produces an output record with the following key value pairs: + +```js +{ sum: 1.6, product: 1.6 } +``` + +The function then processes the next row using this **output record** as the `accumulator`. + +{{% note %}} +Because `reduce()` uses the output record as the `accumulator` when processing the next row, +keys mapped in the `fn` function must match keys in the `identity` and `accumulator` records. +{{% /note %}} + +###### Processing the next row +```js +// Input records for the second row +r = { _time: 2019-04-23T16:10:59.00Z, _value: 2.3 } +accumulator = { sum : 1.6, product : 1.6 } + +// Key mappings for the second row +sum: 2.3 + 1.6 +product: 2.3 * 1.6 + +// Output record of the second row +{ sum: 3.9, product: 3.68 } +``` + +It then uses the new output record as the `accumulator` for the next row. +This cycle continues until all rows in the table are processed. + +##### Final output record and table +After all records in the table are processed, `reduce()` uses the final output record +to create a transformed table with one row and columns for each mapped key. + +###### Final output record +```js +{ sum: 9.6, product: 11.74656 } +``` + +###### Output table +| sum | product | +| --- | -------- | +| 9.6 | 11.74656 | + +{{% note %}} +#### What happened to the \_time column? +The `reduce()` function only keeps columns that are: + +1. Are part of the input table's [group key](/{{< latest "flux" >}}/get-started/data-model/#group-key). +2. Explicitly mapped in the `fn` function. + +It drops all other columns. +Because `_time` is not part of the group key and is not mapped in the `fn` function, +it isn't included in the output table. +{{% /note %}} + +## Custom aggregate function examples +To create custom aggregate functions, use principles outlined in +[Creating custom functions](/influxdb/v2.1/query-data/flux/custom-functions) +and the `reduce()` function to aggregate rows in each input table. + +### Create a custom average function +This example illustrates how to create a function that averages values in a table. +_This is meant for demonstration purposes only. +The built-in [`mean()` function](/{{< latest "flux" >}}/stdlib/universe/mean/) +does the same thing and is much more performant._ + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Comments](#) +[No Comments](#) +{{% /code-tabs %}} + +{{% code-tab-content %}} + +```js +average = (tables=<-, outputField="average") => + tables + |> reduce( + // Define the initial accumulator record + identity: { + count: 1.0, + sum: 0.0, + avg: 0.0 + }, + fn: (r, accumulator) => ({ + // Increment the counter on each reduce loop + count: accumulator.count + 1.0, + // Add the _value to the existing sum + sum: accumulator.sum + r._value, + // Divide the existing sum by the existing count for a new average + avg: accumulator.sum / accumulator.count + }) + ) + // Drop the sum and the count columns since they are no longer needed + |> drop(columns: ["sum", "count"]) + // Set the _field column of the output table to to the value + // provided in the outputField parameter + |> set(key: "_field", value: outputField) + // Rename avg column to _value + |> rename(columns: {avg: "_value"}) +``` +{{% /code-tab-content %}} + +{{% code-tab-content %}} +```js +average = (tables=<-, outputField="average") => + tables + |> reduce( + identity: { + count: 1.0, + sum: 0.0, + avg: 0.0 + }, + fn: (r, accumulator) => ({ + count: accumulator.count + 1.0, + sum: accumulator.sum + r._value, + avg: accumulator.sum / accumulator.count + }) + ) + |> drop(columns: ["sum", "count"]) + |> set(key: "_field", value: outputField) + |> rename(columns: {avg: "_value"}) +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +### Aggregate multiple columns +Built-in aggregate functions only operate on one column. +Use `reduce()` to create a custom aggregate function that aggregates multiple columns. + +The following function expects input tables to have `c1_value` and `c2_value` +columns and generates an average for each. + +```js +multiAvg = (tables=<-) => + tables + |> reduce( + identity: { + count: 1.0, + c1_sum: 0.0, + c1_avg: 0.0, + c2_sum: 0.0, + c2_avg: 0.0 + }, + fn: (r, accumulator) => ({ + count: accumulator.count + 1.0, + c1_sum: accumulator.c1_sum + r.c1_value, + c1_avg: accumulator.c1_sum / accumulator.count, + c2_sum: accumulator.c2_sum + r.c2_value, + c2_avg: accumulator.c2_sum / accumulator.count + }) + ) +``` + +### Aggregate gross and net profit +Use `reduce()` to create a function that aggregates gross and net profit. +This example expects `profit` and `expenses` columns in the input tables. + +```js +profitSummary = (tables=<-) => + tables + |> reduce( + identity: { + gross: 0.0, + net: 0.0 + }, + fn: (r, accumulator) => ({ + gross: accumulator.gross + r.profit, + net: accumulator.net + r.profit - r.expenses + }) + ) +``` diff --git a/content/influxdb/v2.1/query-data/flux/exists.md b/content/influxdb/v2.1/query-data/flux/exists.md new file mode 100644 index 0000000000..028f2d9633 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/exists.md @@ -0,0 +1,86 @@ +--- +title: Check if a value exists +seotitle: Use Flux to check if a value exists +list_title: Exists +description: > + Use the Flux `exists` operator to check if a record contains a key or if that + key's value is `null`. +influxdb/v2.1/tags: [exists] +menu: + influxdb_2_1: + name: Exists + parent: Query with Flux +weight: 220 +aliases: + - /influxdb/v2.1/query-data/guides/exists/ +related: + - /influxdb/v2.1/query-data/flux/query-fields/ + - /{{< latest "flux" >}}/stdlib/universe/filter/ +list_code_example: | + ##### Filter null values + ```js + data + |> filter(fn: (r) => exists r._value) + ``` +--- + +Use the Flux `exists` operator to check if a record contains a key or if that +key's value is `null`. + +```js +p = {firstName: "John", lastName: "Doe", age: 42} + +exists p.firstName +// Returns true + +exists p.height +// Returns false +``` + +If you're just getting started with Flux queries, check out the following: + +- [Get started with Flux](/{{< latest "flux" >}}/get-started/) for a conceptual overview of Flux and parts of a Flux query. +- [Execute queries](/influxdb/v2.1/query-data/execute-queries/) to discover a variety of ways to run your queries. + +Use `exists` with row functions ( +[`filter()`](/{{< latest "flux" >}}/stdlib/universe/filter/), +[`map()`](/{{< latest "flux" >}}/stdlib/universe/map/), +[`reduce()`](/{{< latest "flux" >}}/stdlib/universe/reduce/)) +to check if a row includes a column or if the value for that column is `null`. + +#### Filter null values +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => exists r._value) +``` + +#### Map values based on existence +```js +from(bucket: "default") + |> range(start: -30s) + |> map(fn: (r) => ({ + r with + human_readable: + if exists r._value then "${r._field} is ${string(v:r._value)}." + else "${r._field} has no value." + })) +``` + +#### Ignore null values in a custom aggregate function +```js +customSumProduct = (tables=<-) => + tables + |> reduce( + identity: {sum: 0.0, product: 1.0}, + fn: (r, accumulator) => ({ + r with + sum: + if exists r._value then r._value + accumulator.sum + else accumulator.sum, + product: + if exists r._value then r.value * accumulator.product + else accumulator.product + }) + ) +``` diff --git a/content/influxdb/v2.1/query-data/flux/explore-schema.md b/content/influxdb/v2.1/query-data/flux/explore-schema.md new file mode 100644 index 0000000000..d0cd8711be --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/explore-schema.md @@ -0,0 +1,140 @@ +--- +title: Explore your data schema with Flux +list_title: Explore your schema +description: > + Flux provides functions that let you explore the structure and schema of your + data stored in InfluxDB. +influxdb/v2.1/tags: [schema] +menu: + influxdb_2_1: + name: Explore your schema + parent: Query with Flux +weight: 206 +related: + - /{{< latest "flux" >}}/stdlib/universe/buckets/ + - /{{< latest "flux" >}}/stdlib/schema/measurements + - /{{< latest "flux" >}}/stdlib/schema/fieldkeys + - /{{< latest "flux" >}}/stdlib/schema/measurementfieldkeys + - /{{< latest "flux" >}}/stdlib/schema/tagkeys + - /{{< latest "flux" >}}/stdlib/schema/measurementtagkeys + - /{{< latest "flux" >}}/stdlib/schema/tagvalues + - /{{< latest "flux" >}}/stdlib/schema/measurementtagvalues +list_code_example: | + ```js + import "influxdata/influxdb/schema" + + // List buckets + buckets() + + // List measurements + schema.measurements(bucket: "example-bucket") + + // List field keys + schema.fieldKeys(bucket: "example-bucket") + + // List tag keys + schema.tagKeys(bucket: "example-bucket") + + // List tag values + schema.tagValues(bucket: "example-bucket", tag: "example-tag") + ``` +--- + +Flux provides functions that let you explore the structure and schema of your +data stored in InfluxDB. + +- [List buckets](#list-buckets) +- [List measurements](#list-measurements) +- [List field keys](#list-field-keys) +- [List tag keys](#list-tag-keys) +- [List tag values](#list-tag-values) + +## List buckets +Use the [`buckets()` function](/{{< latest "flux" >}}/stdlib/universe/buckets/) +to list **buckets in your organization**. + +```js +buckets() +``` + +## List measurements +Use the [`schema.measurements()` function](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/measurements) +to list **measurements in a bucket**. + +```js +import "influxdata/influxdb/schema" + +schema.measurements(bucket: "example-bucket") +``` + +## List field keys +Use the [`schema.fieldKeys` function](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/fieldkeys) +to list **field keys in a bucket**. + +```js +import "influxdata/influxdb/schema" + +schema.fieldKeys(bucket: "example-bucket") +``` + +### List fields in a measurement +Use the [`schema.measurementFieldKeys` function](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/measurementfieldkeys) +to list **field keys in a measurement**. + +```js +import "influxdata/influxdb/schema" + +schema.measurementFieldKeys( + bucket: "example-bucket", + measurement: "example-measurement" +) +``` + +## List tag keys +Use the [`schema.tagKeys()` function](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/tagkeys) +to list **tag keys in a bucket**. + +```js +import "influxdata/influxdb/schema" + +schema.tagKeys(bucket: "example-bucket") +``` + +### List tag keys in a measurement +Use the [`schema.measurementTagKeys` function](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/measurementtagkeys) +to list **tag keys in a measurement**. +_This function returns results from the last 30 days._ + +```js +import "influxdata/influxdb/schema" + +schema.measurementTagKeys( + bucket: "example-bucket", + measurement: "example-measurement" +) +``` + +## List tag values +Use the [`schema.tagValues()` function](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/tagvalues) +to list **tag values for a given tag in a bucket**. + +```js +import "influxdata/influxdb/schema" + +schema.tagValues(bucket: "example-bucket", tag: "example-tag") +``` + +### List tag values in a measurement +Use the [`schema.measurementTagValues` function](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/measurementtagvalues) +to list **tag values for a given tag in a measurement**. +_This function returns results from the last 30 days._ + +```js +import "influxdata/influxdb/schema" + +schema.measurementTagValues( + bucket: "example-bucket", + tag: "example-tag", + measurement: "example-measurement" +) +``` diff --git a/content/influxdb/v2.1/query-data/flux/fill.md b/content/influxdb/v2.1/query-data/flux/fill.md new file mode 100644 index 0000000000..f966dbc1d3 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/fill.md @@ -0,0 +1,113 @@ +--- +title: Fill null values in data +seotitle: Fill null values in data +list_title: Fill +description: > + Use `fill()` function to replace _null_ values. +weight: 210 +menu: + influxdb_2_1: + parent: Query with Flux + name: Fill +influxdb/v2.1/tags: [query, fill] +related: + - /{{< latest "flux" >}}/stdlib/universe/fill/ +list_query_example: fill_null +--- + +Use [`fill()`](/{{< latest "flux" >}}/stdlib/universe/fill/) +to replace _null_ values with: + +- [the previous non-null value](#fill-with-the-previous-value) +- [a specified value](#fill-with-a-specified-value) + + +```js +data + |> fill(usePrevious: true) + +// OR + +data + |> fill(value: 0.0) +``` + +{{% note %}} +#### Fill empty windows of time +The `fill()` function **does not** fill empty windows of time. +It only replaces _null_ values in existing data. +Filling empty windows of time requires time interpolation +_(see [influxdata/flux#2428](https://github.com/influxdata/flux/issues/2428))_. +{{% /note %}} + +## Fill with the previous value +To fill _null_ values with the previous **non-null** value, set the `usePrevious` parameter to `true`. + +{{% note %}} +Values remain _null_ if there is no previous non-null value in the table. +{{% /note %}} + +```js +data + |> fill(usePrevious: true) +``` + +{{< flex >}} +{{% flex-content %}} +**Given the following input:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:01:00Z | null | +| 2020-01-01T00:02:00Z | 0.8 | +| 2020-01-01T00:03:00Z | null | +| 2020-01-01T00:04:00Z | null | +| 2020-01-01T00:05:00Z | 1.4 | +{{% /flex-content %}} +{{% flex-content %}} +**`fill(usePrevious: true)` returns:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:01:00Z | null | +| 2020-01-01T00:02:00Z | 0.8 | +| 2020-01-01T00:03:00Z | 0.8 | +| 2020-01-01T00:04:00Z | 0.8 | +| 2020-01-01T00:05:00Z | 1.4 | +{{% /flex-content %}} +{{< /flex >}} + +## Fill with a specified value +To fill _null_ values with a specified value, use the `value` parameter to specify the fill value. +_The fill value must match the [data type](/{{< latest "flux" >}}/spec/types/#basic-types) +of the [column](/{{< latest "flux" >}}/stdlib/universe/fill/#column)._ + +```js +data + |> fill(value: 0.0) +``` + +{{< flex >}} +{{% flex-content %}} +**Given the following input:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:01:00Z | null | +| 2020-01-01T00:02:00Z | 0.8 | +| 2020-01-01T00:03:00Z | null | +| 2020-01-01T00:04:00Z | null | +| 2020-01-01T00:05:00Z | 1.4 | +{{% /flex-content %}} +{{% flex-content %}} +**`fill(value: 0.0)` returns:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:01:00Z | 0.0 | +| 2020-01-01T00:02:00Z | 0.8 | +| 2020-01-01T00:03:00Z | 0.0 | +| 2020-01-01T00:04:00Z | 0.0 | +| 2020-01-01T00:05:00Z | 1.4 | +{{% /flex-content %}} +{{< /flex >}} diff --git a/content/influxdb/v2.1/query-data/flux/first-last.md b/content/influxdb/v2.1/query-data/flux/first-last.md new file mode 100644 index 0000000000..16e5b697fd --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/first-last.md @@ -0,0 +1,151 @@ +--- +title: Query first and last values +seotitle: Query first and last values in Flux +list_title: First and last +description: > + Use `first()` or `last()` to return the first or last point in an input table. +weight: 210 +menu: + influxdb_2_1: + parent: Query with Flux + name: First & last +influxdb/v2.1/tags: [query] +related: + - /{{< latest "flux" >}}/stdlib/universe/first/ + - /{{< latest "flux" >}}/stdlib/universe/last/ +list_query_example: first_last +--- + +Use [`first()`](/{{< latest "flux" >}}/stdlib/universe/first/) or +[`last()`](/{{< latest "flux" >}}/stdlib/universe/last/) to return the first or +last record in an input table. + +```js +data + |> first() + +// OR + +data + |> last() +``` + +{{% note %}} +By default, InfluxDB returns results sorted by time, however you can use the +[`sort()` function](/{{< latest "flux" >}}/stdlib/universe/sort/) +to change how results are sorted. +`first()` and `last()` respect the sort order of input data and return records +based on the order they are received in. +{{% /note %}} + +### first +`first()` returns the first non-null record in an input table. + +{{< flex >}} +{{% flex-content %}} +**Given the following input:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:01:00Z | 1.0 | +| 2020-01-01T00:02:00Z | 1.0 | +| 2020-01-01T00:03:00Z | 2.0 | +| 2020-01-01T00:04:00Z | 3.0 | +{{% /flex-content %}} +{{% flex-content %}} +**The following function returns:** +```js +|> first() +``` + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:01:00Z | 1.0 | +{{% /flex-content %}} +{{< /flex >}} + +### last +`last()` returns the last non-null record in an input table. + +{{< flex >}} +{{% flex-content %}} +**Given the following input:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:01:00Z | 1.0 | +| 2020-01-01T00:02:00Z | 1.0 | +| 2020-01-01T00:03:00Z | 2.0 | +| 2020-01-01T00:04:00Z | 3.0 | +{{% /flex-content %}} +{{% flex-content %}} +**The following function returns:** + +```js +|> last() +``` + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:04:00Z | 3.0 | +{{% /flex-content %}} +{{< /flex >}} + +## Use first() or last() with aggregateWindow() +Use `first()` and `last()` with [`aggregateWindow()`](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow/) +to select the first or last records in time-based groups. +`aggregateWindow()` segments data into windows of time, aggregates data in each window into a single +point using aggregate or selector functions, and then removes the time-based segmentation. + + +{{< flex >}} +{{% flex-content %}} +**Given the following input:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:00:00Z | 10 | +| 2020-01-01T00:00:15Z | 12 | +| 2020-01-01T00:00:45Z | 9 | +| 2020-01-01T00:01:05Z | 9 | +| 2020-01-01T00:01:10Z | 15 | +| 2020-01-01T00:02:30Z | 11 | +{{% /flex-content %}} + +{{% flex-content %}} +**The following function returns:** +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[first](#) +[last](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```js +|> aggregateWindow( + every: 1h, + fn: first +) +``` +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:00:59Z | 10 | +| 2020-01-01T00:01:59Z | 9 | +| 2020-01-01T00:02:59Z | 11 | +{{% /code-tab-content %}} +{{% code-tab-content %}} +```js +|> aggregateWindow( + every: 1h, + fn: last +) +``` + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:00:59Z | 9 | +| 2020-01-01T00:01:59Z | 15 | +| 2020-01-01T00:02:59Z | 11 | +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} +{{%/flex-content %}} +{{< /flex >}} diff --git a/content/influxdb/v2.1/query-data/flux/geo/_index.md b/content/influxdb/v2.1/query-data/flux/geo/_index.md new file mode 100644 index 0000000000..0c835ed753 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/geo/_index.md @@ -0,0 +1,69 @@ +--- +title: Work with geo-temporal data +list_title: Geo-temporal data +description: > + Use the Flux Geo package to filter geo-temporal data and group by geographic location or track. +menu: + influxdb_2_1: + name: Geo-temporal data + parent: Query with Flux +weight: 220 +list_code_example: | + ```js + import "experimental/geo" + + sampleGeoData + |> geo.filterRows(region: {lat: 30.04, lon: 31.23, radius: 200.0}) + |> geo.groupByArea(newColumn: "geoArea", level: 5) + ``` +--- + +Use the [Flux Geo package](/{{< latest "flux" >}}/stdlib/experimental/to/geo) to +filter geo-temporal data and group by geographic location or track. + +{{% warn %}} +The Geo package is experimental and subject to change at any time. +By using it, you agree to the [risks of experimental functions](/{{< latest "flux" >}}/stdlib/experimental/to/#experimental-functions-are-subject-to-change). +{{% /warn %}} + +**To work with geo-temporal data:** + +1. Import the `experimental/geo` package. + + ```js + import "experimental/geo" + ``` + +2. Load geo-temporal data. _See below for [sample geo-temporal data](#sample-data)._ +3. Do one or more of the following: + + - [Shape data to work with the Geo package](#shape-data-to-work-with-the-geo-package) + - [Filter data by region](#filter-geo-temporal-data-by-region) (using strict or non-strict filters) + - [Group data by area or by track](#group-geo-temporal-data) + +{{< children >}} + +--- + +## Sample data +Many of the examples in this section use a `sampleGeoData` variable that represents +a sample set of geo-temporal data. +The [Bird Migration Sample Data](/influxdb/v2.1/reference/sample-data/#bird-migration-sample-data) +provides sample geo-temporal data that meets the +[requirements of the Flux Geo package](/{{< latest "flux" >}}/stdlib/experimental/geo/#geo-schema-requirements). + +### Load bird migration sample data +Use the [`sample.data()` function](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/sample/data/) +to load the sample bird migration data: + +```js +import "influxdata/influxdb/sample" + +sampleGeoData = sample.data(set: "birdMigration") +``` + +{{% note %}} +`sample.data()` downloads sample data each time you execute the query **(~1.3 MB)**. +If bandwidth is a concern, use the [`to()` function](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/to/) +to write the data to a bucket, and then query the bucket with [`from()`](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/from/). +{{% /note %}} diff --git a/content/influxdb/v2.1/query-data/flux/geo/filter-by-region.md b/content/influxdb/v2.1/query-data/flux/geo/filter-by-region.md new file mode 100644 index 0000000000..894eaac686 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/geo/filter-by-region.md @@ -0,0 +1,130 @@ +--- +title: Filter geo-temporal data by region +description: > + Use the `geo.filterRows` function to filter geo-temporal data by box-shaped, circular, or polygonal geographic regions. +menu: + influxdb_2_1: + name: Filter by region + parent: Geo-temporal data +weight: 302 +related: + - /{{< latest "flux" >}}/stdlib/experimental/geo/ + - /{{< latest "flux" >}}/stdlib/experimental/geo/filterrows/ +list_code_example: | + ```js + import "experimental/geo" + + sampleGeoData + |> geo.filterRows( + region: {lat: 30.04, lon: 31.23, radius: 200.0}, + strict: true + ) + ``` +--- + +Use the [`geo.filterRows` function](/{{< latest "flux" >}}/stdlib/experimental/to/geo/filterrows/) +to filter geo-temporal data by geographic region: + +1. [Define a geographic region](#define-a-geographic-region) +2. [Use strict or non-strict filtering](#strict-and-non-strict-filtering) + +The following example uses the [sample bird migration data](/influxdb/v2.1/query-data/flux/geo/#sample-data) +and queries data points **within 200km of Cairo, Egypt**: + +```js +import "experimental/geo" + +sampleGeoData + |> geo.filterRows( + region: {lat: 30.04, lon: 31.23, radius: 200.0}, + strict: true + ) +``` + +## Define a geographic region +Many functions in the Geo package filter data based on geographic region. +Define a geographic region using one of the the following shapes: + +- [box](#box) +- [circle](#circle) +- [polygon](#polygon) + +### box +Define a box-shaped region by specifying a record containing the following properties: + +- **minLat:** minimum latitude in decimal degrees (WGS 84) _(Float)_ +- **maxLat:** maximum latitude in decimal degrees (WGS 84) _(Float)_ +- **minLon:** minimum longitude in decimal degrees (WGS 84) _(Float)_ +- **maxLon:** maximum longitude in decimal degrees (WGS 84) _(Float)_ + +##### Example box-shaped region +```js +{ + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} +``` + +### circle +Define a circular region by specifying a record containing the following properties: + +- **lat**: latitude of the circle center in decimal degrees (WGS 84) _(Float)_ +- **lon**: longitude of the circle center in decimal degrees (WGS 84) _(Float)_ +- **radius**: radius of the circle in kilometers (km) _(Float)_ + +##### Example circular region +```js +{ + lat: 40.69335938, + lon: -73.30078125, + radius: 20.0 +} +``` + +### polygon +Define a polygonal region with a record containing the latitude and longitude for +each point in the polygon: + +- **points**: points that define the custom polygon _(Array of records)_ + + Define each point with a record containing the following properties: + + - **lat**: latitude in decimal degrees (WGS 84) _(Float)_ + - **lon**: longitude in decimal degrees (WGS 84) _(Float)_ + +##### Example polygonal region +```js +{ + points: [ + {lat: 40.671659, lon: -73.936631}, + {lat: 40.706543, lon: -73.749177}, + {lat: 40.791333, lon: -73.880327} + ] +} +``` + +## Strict and non-strict filtering +In most cases, the specified geographic region does not perfectly align with S2 grid cells. + +- **Non-strict filtering** returns points that may be outside of the specified region but + inside S2 grid cells partially covered by the region. +- **Strict filtering** returns only points inside the specified region. + +_Strict filtering is less performant, but more accurate than non-strict filtering._ + + S2 grid cell + Filter region + Returned point + +{{< flex >}} +{{% flex-content %}} +**Strict filtering** +{{< svg "/static/svgs/geo-strict.svg" >}} +{{% /flex-content %}} +{{% flex-content %}} +**Non-strict filtering** +{{< svg "/static/svgs/geo-non-strict.svg" >}} +{{% /flex-content %}} +{{< /flex >}} diff --git a/content/influxdb/v2.1/query-data/flux/geo/group-geo-data.md b/content/influxdb/v2.1/query-data/flux/geo/group-geo-data.md new file mode 100644 index 0000000000..ac88f23712 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/geo/group-geo-data.md @@ -0,0 +1,79 @@ +--- +title: Group geo-temporal data +description: > + Use the `geo.groupByArea()` to group geo-temporal data by area and `geo.asTracks()` + to group data into tracks or routes. +menu: + influxdb_2_1: + parent: Geo-temporal data +weight: 302 +related: + - /{{< latest "flux" >}}/stdlib/experimental/geo/ + - /{{< latest "flux" >}}/stdlib/experimental/geo/groupbyarea/ + - /{{< latest "flux" >}}/stdlib/experimental/geo/astracks/ +list_code_example: | + ```js + import "experimental/geo" + + sampleGeoData + |> geo.groupByArea(newColumn: "geoArea", level: 5) + |> geo.asTracks(groupBy: ["id"],sortBy: ["_time"]) + ``` +--- + +Use the `geo.groupByArea()` to group geo-temporal data by area and `geo.asTracks()` +to group data into tracks or routes. + +- [Group data by area](#group-data-by-area) +- [Group data into tracks or routes](#group-data-by-track-or-route) + +{{% note %}} +For example results, use the [bird migration sample data](/influxdb/v2.1/reference/sample-data/#bird-migration-sample-data) +to populate the `sampleGeoData` variable in the queries below. +{{% /note %}} + +### Group data by area +Use the [`geo.groupByArea()` function](/{{< latest "flux" >}}/stdlib/experimental/to/geo/groupbyarea/) +to group geo-temporal data points by geographic area. +Areas are determined by [S2 grid cells](https://s2geometry.io/devguide/s2cell_hierarchy.html#s2cellid-numbering) + +- Specify a new column to store the unique area identifier for each point with the `newColumn` parameter. +- Specify the [S2 cell level](https://s2geometry.io/resources/s2cell_statistics) + to use when calculating geographic areas with the `level` parameter. + +The following example uses the [sample bird migration data](/influxdb/v2.1/query-data/flux/geo/#sample-data) +to query data points within 200km of Cairo, Egypt and group them by geographic area: + +```js +import "experimental/geo" + +sampleGeoData + |> geo.filterRows(region: {lat: 30.04, lon: 31.23, radius: 200.0}) + |> geo.groupByArea( + newColumn: "geoArea", + level: 5 + ) +``` + +### Group data by track or route +Use [`geo.asTracks()` function](/{{< latest "flux" >}}/stdlib/experimental/to/geo/astracks/) +to group data points into tracks or routes and order them by time or other columns. +Data must contain a unique identifier for each track. For example: `id` or `tid`. + +- Specify columns that uniquely identify each track or route with the `groupBy` parameter. +- Specify which columns to sort by with the `sortBy` parameter. Default is `["_time"]`. + +The following example uses the [sample bird migration data](/influxdb/v2.1/query-data/flux/geo/#sample-data) +to query data points within 200km of Cairo, Egypt and group them into routes unique +to each bird: + +```js +import "experimental/geo" + +sampleGeoData + |> geo.filterRows(region: {lat: 30.04, lon: 31.23, radius: 200.0}) + |> geo.asTracks( + groupBy: ["id"], + orderBy: ["_time"] + ) +``` diff --git a/content/influxdb/v2.1/query-data/flux/geo/shape-geo-data.md b/content/influxdb/v2.1/query-data/flux/geo/shape-geo-data.md new file mode 100644 index 0000000000..a222c2d799 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/geo/shape-geo-data.md @@ -0,0 +1,121 @@ +--- +title: Shape data to work with the Geo package +description: > + Functions in the Flux Geo package require **lat** and **lon** fields and an **s2_cell_id** tag. + Rename latitude and longitude fields and generate S2 cell ID tokens. +menu: + influxdb_2_1: + name: Shape geo-temporal data + parent: Geo-temporal data +weight: 301 +related: + - /{{< latest "flux" >}}/stdlib/experimental/geo/ + - /{{< latest "flux" >}}/stdlib/experimental/geo/shapedata/ +list_code_example: | + ```js + import "experimental/geo" + + sampleGeoData + |> geo.shapeData(latField: "latitude", lonField: "longitude", level: 10) + ``` +--- + +Functions in the Geo package require the following data schema: + +- an **s2_cell_id** tag containing the [S2 Cell ID](https://s2geometry.io/devguide/s2cell_hierarchy.html#s2cellid-numbering) + **as a token** +- a **`lat` field** field containing the **latitude in decimal degrees** (WGS 84) +- a **`lon` field** field containing the **longitude in decimal degrees** (WGS 84) + +## Shape geo-temporal data +If your data already contains latitude and longitude fields, use the +[`geo.shapeData()`function](/{{< latest "flux" >}}/stdlib/experimental/to/geo/shapedata/) +to rename the fields to match the requirements of the Geo package, pivot the data +into row-wise sets, and generate S2 cell ID tokens for each point. + +```js +import "experimental/geo" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> geo.shapeData( + latField: "latitude", + lonField: "longitude", + level: 10 + ) +``` + +## Generate S2 cell ID tokens +The Geo package uses the [S2 Geometry Library](https://s2geometry.io/) to represent +geographic coordinates on a three-dimensional sphere. +The sphere is divided into [cells](https://s2geometry.io/devguide/s2cell_hierarchy), +each with a unique 64-bit identifier (S2 cell ID). +Grid and S2 cell ID accuracy are defined by a [level](https://s2geometry.io/resources/s2cell_statistics). + +{{% note %}} +To filter more quickly, use higher S2 Cell ID levels, +but know that that higher levels increase [series cardinality](/influxdb/v2.1/reference/glossary/#series-cardinality). +{{% /note %}} + +The Geo package requires S2 cell IDs as tokens. +To generate add S2 cell IDs tokens to your data, use one of the following options: + +- [Generate S2 cell ID tokens with Telegraf](#generate-s2-cell-id-tokens-with-telegraf) +- [Generate S2 cell ID tokens language-specific libraries](#generate-s2-cell-id-tokens-language-specific-libraries) +- [Generate S2 cell ID tokens with Flux](#generate-s2-cell-id-tokens-with-flux) + +### Generate S2 cell ID tokens with Telegraf +Enable the [Telegraf S2 Geo (`s2geo`) processor](https://github.com/influxdata/telegraf/tree/master/plugins/processors/s2geo) +to generate S2 cell ID tokens at a specified `cell_level` using `lat` and `lon` field values. + +Add the `processors.s2geo` configuration to your Telegraf configuration file (`telegraf.conf`): + +```toml +[[processors.s2geo]] + ## The name of the lat and lon fields containing WGS-84 latitude and + ## longitude in decimal degrees. + lat_field = "lat" + lon_field = "lon" + + ## New tag to create + tag_key = "s2_cell_id" + + ## Cell level (see https://s2geometry.io/resources/s2cell_statistics.html) + cell_level = 9 +``` + +Telegraf stores the S2 cell ID token in the `s2_cell_id` tag. + +### Generate S2 cell ID tokens language-specific libraries +Many programming languages offer S2 Libraries with methods for generating S2 cell ID tokens. +Use latitude and longitude with the `s2.CellID.ToToken` endpoint of the S2 Geometry +Library to generate `s2_cell_id` tags. For example: + +- **Go:** [s2.CellID.ToToken()](https://godoc.org/github.com/golang/geo/s2#CellID.ToToken) +- **Python:** [s2sphere.CellId.to_token()](https://s2sphere.readthedocs.io/en/latest/api.html#s2sphere.CellId) +- **Crystal:** [cell.to_token(level)](https://github.com/spider-gazelle/s2_cells#usage) +- **JavaScript:** [s2.cellid.toToken()](https://github.com/mapbox/node-s2/blob/master/API.md#cellidtotoken---string) + +### Generate S2 cell ID tokens with Flux +Use the [`geo.s2CellIDToken()` function](/{{< latest "flux" >}}/stdlib/experimental/to/geo/s2cellidtoken/) +with existing longitude (`lon`) and latitude (`lat`) field values to generate and add the S2 cell ID token. +First, use the [`geo.toRows()` function](/{{< latest "flux" >}}/stdlib/experimental/to/geo/torows/) +to pivot **lat** and **lon** fields into row-wise sets: + +```js +import "experimental/geo" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> geo.toRows() + |> map(fn: (r) => ({ r with + s2_cell_id: geo.s2CellIDToken(point: {lon: r.lon, lat: r.lat}, level: 10) + })) +``` + +{{% note %}} +The [`geo.shapeData()`function](/{{< latest "flux" >}}/stdlib/experimental/to/geo/shapedata/) +generates S2 cell ID tokens as well. +{{% /note %}} diff --git a/content/influxdb/v2.1/query-data/flux/group-data.md b/content/influxdb/v2.1/query-data/flux/group-data.md new file mode 100644 index 0000000000..b8e4373912 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/group-data.md @@ -0,0 +1,678 @@ +--- +title: Group data in InfluxDB with Flux +list_title: Group +description: > + Use `group()` to group data with common values in specific columns. +influxdb/v2.1/tags: [group] +menu: + influxdb_2_1: + name: Group + parent: Query with Flux +weight: 202 +aliases: + - /influxdb/v2.1/query-data/guides/group-data/ +related: + - /{{< latest "flux" >}}/stdlib/universe/group + - /{{< latest "flux" >}}/stdlib/experimental/group +list_query_example: group +--- + +With Flux, you can group data by any column in your queried data set. +"Grouping" partitions data into tables in which each row shares a common value for specified columns. +This guide walks through grouping data in Flux and provides examples of how data is shaped in the process. + +If you're just getting started with Flux queries, check out the following: + +- [Get started with Flux](/{{< latest "flux" >}}/get-started/) for a conceptual overview of Flux and parts of a Flux query. +- [Execute queries](/influxdb/v2.1/query-data/execute-queries/) to discover a variety of ways to run your queries. + +## Group keys +Every table has a **group key** – a list of columns for which every row in the table has the same value. + +###### Example group key +```js +[_start, _stop, _field, _measurement, host] +``` + +Grouping data in Flux is essentially defining the group key of output tables. +Understanding how modifying group keys shapes output data is key to successfully +grouping and transforming data into your desired output. + +## group() Function +Flux's [`group()` function](/{{< latest "flux" >}}/stdlib/universe/group) defines the +group key for output tables, i.e. grouping records based on values for specific columns. + +###### group() example +```js +dataStream + |> group(columns: ["cpu", "host"]) +``` + +###### Resulting group key +```js +[cpu, host] +``` + +The `group()` function has the following parameters: + +### columns +The list of columns to include or exclude (depending on the [mode](#mode)) in the grouping operation. + +### mode +The method used to define the group and resulting group key. +Possible values include `by` and `except`. + + +## Example grouping operations +To illustrate how grouping works, define a `dataSet` variable that queries System +CPU usage from the `example-bucket` bucket. +Filter the `cpu` tag so it only returns results for each numbered CPU core. + +### Data set +CPU used by system operations for all numbered CPU cores. +It uses a regular expression to filter only numbered cores. + +```js +dataSet = from(bucket: "example-bucket") + |> range(start: -2m) + |> filter(fn: (r) => + r._field == "usage_system" and + r.cpu =~ /cpu[0-9*]/ + ) + |> drop(columns: ["host"]) +``` + +{{% note %}} +This example drops the `host` column from the returned data since the CPU data +is only tracked for a single host and it simplifies the output tables. +Don't drop the `host` column if monitoring multiple hosts. +{{% /note %}} + +{{% truncate %}} +``` +Table: keys: [_start, _stop, _field, _measurement, cpu] + _start:time _stop:time _field:string _measurement:string cpu:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:34:00.000000000Z 7.892107892107892 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:34:10.000000000Z 7.2 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:34:20.000000000Z 7.4 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:34:30.000000000Z 5.5 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:34:40.000000000Z 7.4 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:34:50.000000000Z 7.5 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:35:00.000000000Z 10.3 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:35:10.000000000Z 9.2 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:35:20.000000000Z 8.4 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:35:30.000000000Z 8.5 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:35:40.000000000Z 8.6 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:35:50.000000000Z 10.2 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu0 2018-11-05T21:36:00.000000000Z 10.6 + +Table: keys: [_start, _stop, _field, _measurement, cpu] + _start:time _stop:time _field:string _measurement:string cpu:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:34:00.000000000Z 0.7992007992007992 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:34:10.000000000Z 0.7 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:34:20.000000000Z 0.7 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:34:30.000000000Z 0.4 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:34:40.000000000Z 0.7 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:34:50.000000000Z 0.7 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:35:00.000000000Z 1.4 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:35:10.000000000Z 1.2 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:35:20.000000000Z 0.8 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:35:30.000000000Z 0.8991008991008991 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:35:40.000000000Z 0.8008008008008008 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:35:50.000000000Z 0.999000999000999 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu1 2018-11-05T21:36:00.000000000Z 1.1022044088176353 + +Table: keys: [_start, _stop, _field, _measurement, cpu] + _start:time _stop:time _field:string _measurement:string cpu:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:34:00.000000000Z 4.1 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:34:10.000000000Z 3.6 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:34:20.000000000Z 3.5 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:34:30.000000000Z 2.6 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:34:40.000000000Z 4.5 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:34:50.000000000Z 4.895104895104895 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:35:00.000000000Z 6.906906906906907 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:35:10.000000000Z 5.7 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:35:20.000000000Z 5.1 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:35:30.000000000Z 4.7 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:35:40.000000000Z 5.1 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:35:50.000000000Z 5.9 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu2 2018-11-05T21:36:00.000000000Z 6.4935064935064934 + +Table: keys: [_start, _stop, _field, _measurement, cpu] + _start:time _stop:time _field:string _measurement:string cpu:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:34:00.000000000Z 0.5005005005005005 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:34:10.000000000Z 0.5 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:34:20.000000000Z 0.5 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:34:30.000000000Z 0.3 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:34:40.000000000Z 0.6 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:34:50.000000000Z 0.6 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:35:00.000000000Z 1.3986013986013985 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:35:10.000000000Z 0.9 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:35:20.000000000Z 0.5005005005005005 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:35:30.000000000Z 0.7 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:35:40.000000000Z 0.6 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:35:50.000000000Z 0.8 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z usage_system cpu cpu3 2018-11-05T21:36:00.000000000Z 0.9 +``` +{{% /truncate %}} + +**Note that the group key is output with each table: `Table: keys: `.** + +![Group example data set](/img/flux/grouping-data-set.png) + +### Group by CPU +Group the `dataSet` stream by the `cpu` column. + +```js +dataSet + |> group(columns: ["cpu"]) +``` + +This won't actually change the structure of the data since it already has `cpu` +in the group key and is therefore grouped by `cpu`. +However, notice that it does change the group key: + +{{% truncate %}} +###### Group by CPU output tables +``` +Table: keys: [cpu] + cpu:string _stop:time _time:time _value:float _field:string _measurement:string _start:time +---------------------- ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ + cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:00.000000000Z 7.892107892107892 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:10.000000000Z 7.2 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:20.000000000Z 7.4 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:30.000000000Z 5.5 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:40.000000000Z 7.4 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:50.000000000Z 7.5 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:00.000000000Z 10.3 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:10.000000000Z 9.2 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:20.000000000Z 8.4 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:30.000000000Z 8.5 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:40.000000000Z 8.6 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:50.000000000Z 10.2 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu0 2018-11-05T21:36:00.000000000Z 2018-11-05T21:36:00.000000000Z 10.6 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [cpu] + cpu:string _stop:time _time:time _value:float _field:string _measurement:string _start:time +---------------------- ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ + cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:00.000000000Z 0.7992007992007992 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:10.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:20.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:30.000000000Z 0.4 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:40.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:50.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:00.000000000Z 1.4 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:10.000000000Z 1.2 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:20.000000000Z 0.8 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:30.000000000Z 0.8991008991008991 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:40.000000000Z 0.8008008008008008 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:50.000000000Z 0.999000999000999 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu1 2018-11-05T21:36:00.000000000Z 2018-11-05T21:36:00.000000000Z 1.1022044088176353 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [cpu] + cpu:string _stop:time _time:time _value:float _field:string _measurement:string _start:time +---------------------- ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ + cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:00.000000000Z 4.1 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:10.000000000Z 3.6 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:20.000000000Z 3.5 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:30.000000000Z 2.6 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:40.000000000Z 4.5 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:50.000000000Z 4.895104895104895 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:00.000000000Z 6.906906906906907 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:10.000000000Z 5.7 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:20.000000000Z 5.1 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:30.000000000Z 4.7 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:40.000000000Z 5.1 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:50.000000000Z 5.9 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu2 2018-11-05T21:36:00.000000000Z 2018-11-05T21:36:00.000000000Z 6.4935064935064934 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [cpu] + cpu:string _stop:time _time:time _value:float _field:string _measurement:string _start:time +---------------------- ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ + cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:00.000000000Z 0.5005005005005005 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:10.000000000Z 0.5 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:20.000000000Z 0.5 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:30.000000000Z 0.3 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:40.000000000Z 0.6 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:50.000000000Z 0.6 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:00.000000000Z 1.3986013986013985 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:10.000000000Z 0.9 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:20.000000000Z 0.5005005005005005 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:30.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:40.000000000Z 0.6 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:35:50.000000000Z 0.8 usage_system cpu 2018-11-05T21:34:00.000000000Z + cpu3 2018-11-05T21:36:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.9 usage_system cpu 2018-11-05T21:34:00.000000000Z +``` +{{% /truncate %}} + +The visualization remains the same. + +![Group by CPU](/img/flux/grouping-data-set.png) + +### Group by time +Grouping data by the `_time` column is a good illustration of how grouping changes the structure of your data. + +```js +dataSet + |> group(columns: ["_time"]) +``` + +When grouping by `_time`, all records that share a common `_time` value are grouped into individual tables. +So each output table represents a single point in time. + +{{% truncate %}} +###### Group by time output tables +``` +Table: keys: [_time] + _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string +------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- +2018-11-05T21:34:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 7.892107892107892 usage_system cpu cpu0 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.7992007992007992 usage_system cpu cpu1 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 4.1 usage_system cpu cpu2 +2018-11-05T21:34:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.5005005005005005 usage_system cpu cpu3 + +Table: keys: [_time] + _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string +------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- +2018-11-05T21:34:10.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 7.2 usage_system cpu cpu0 +2018-11-05T21:34:10.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu cpu1 +2018-11-05T21:34:10.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 3.6 usage_system cpu cpu2 +2018-11-05T21:34:10.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.5 usage_system cpu cpu3 + +Table: keys: [_time] + _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string +------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- +2018-11-05T21:34:20.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 7.4 usage_system cpu cpu0 +2018-11-05T21:34:20.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu cpu1 +2018-11-05T21:34:20.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 3.5 usage_system cpu cpu2 +2018-11-05T21:34:20.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.5 usage_system cpu cpu3 + +Table: keys: [_time] + _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string +------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- +2018-11-05T21:34:30.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 5.5 usage_system cpu cpu0 +2018-11-05T21:34:30.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.4 usage_system cpu cpu1 +2018-11-05T21:34:30.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 2.6 usage_system cpu cpu2 +2018-11-05T21:34:30.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.3 usage_system cpu cpu3 + +Table: keys: [_time] + _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string +------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- +2018-11-05T21:34:40.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 7.4 usage_system cpu cpu0 +2018-11-05T21:34:40.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu cpu1 +2018-11-05T21:34:40.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 4.5 usage_system cpu cpu2 +2018-11-05T21:34:40.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.6 usage_system cpu cpu3 + +Table: keys: [_time] + _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string +------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- +2018-11-05T21:34:50.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 7.5 usage_system cpu cpu0 +2018-11-05T21:34:50.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu cpu1 +2018-11-05T21:34:50.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 4.895104895104895 usage_system cpu cpu2 +2018-11-05T21:34:50.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.6 usage_system cpu cpu3 + +Table: keys: [_time] + _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string +------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- +2018-11-05T21:35:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 10.3 usage_system cpu cpu0 +2018-11-05T21:35:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 1.4 usage_system cpu cpu1 +2018-11-05T21:35:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 6.906906906906907 usage_system cpu cpu2 +2018-11-05T21:35:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 1.3986013986013985 usage_system cpu cpu3 + +Table: keys: [_time] + _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string +------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- +2018-11-05T21:35:10.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 9.2 usage_system cpu cpu0 +2018-11-05T21:35:10.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 1.2 usage_system cpu cpu1 +2018-11-05T21:35:10.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 5.7 usage_system cpu cpu2 +2018-11-05T21:35:10.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.9 usage_system cpu cpu3 + +Table: keys: [_time] + _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string +------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- +2018-11-05T21:35:20.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 8.4 usage_system cpu cpu0 +2018-11-05T21:35:20.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.8 usage_system cpu cpu1 +2018-11-05T21:35:20.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 5.1 usage_system cpu cpu2 +2018-11-05T21:35:20.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.5005005005005005 usage_system cpu cpu3 + +Table: keys: [_time] + _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string +------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- +2018-11-05T21:35:30.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 8.5 usage_system cpu cpu0 +2018-11-05T21:35:30.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.8991008991008991 usage_system cpu cpu1 +2018-11-05T21:35:30.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 4.7 usage_system cpu cpu2 +2018-11-05T21:35:30.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu cpu3 + +Table: keys: [_time] + _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string +------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- +2018-11-05T21:35:40.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 8.6 usage_system cpu cpu0 +2018-11-05T21:35:40.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.8008008008008008 usage_system cpu cpu1 +2018-11-05T21:35:40.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 5.1 usage_system cpu cpu2 +2018-11-05T21:35:40.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.6 usage_system cpu cpu3 + +Table: keys: [_time] + _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string +------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- +2018-11-05T21:35:50.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 10.2 usage_system cpu cpu0 +2018-11-05T21:35:50.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.999000999000999 usage_system cpu cpu1 +2018-11-05T21:35:50.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 5.9 usage_system cpu cpu2 +2018-11-05T21:35:50.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.8 usage_system cpu cpu3 + +Table: keys: [_time] + _time:time _start:time _stop:time _value:float _field:string _measurement:string cpu:string +------------------------------ ------------------------------ ------------------------------ ---------------------------- ---------------------- ---------------------- ---------------------- +2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 10.6 usage_system cpu cpu0 +2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 1.1022044088176353 usage_system cpu cpu1 +2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 6.4935064935064934 usage_system cpu cpu2 +2018-11-05T21:36:00.000000000Z 2018-11-05T21:34:00.000000000Z 2018-11-05T21:36:00.000000000Z 0.9 usage_system cpu cpu3 +``` +{{% /truncate %}} + +Because each timestamp is structured as a separate table, when visualized, all +points that share the same timestamp appear connected. + +![Group by time](/img/flux/grouping-by-time.png) + +{{% note %}} +With some further processing, you could calculate the average CPU usage across all CPUs per point +of time and group them into a single table, but we won't cover that in this example. +If you're interested in running and visualizing this yourself, here's what the query would look like: + +```js +dataSet + |> group(columns: ["_time"]) + |> mean() + |> group(columns: ["_value", "_time"], mode: "except") +``` +{{% /note %}} + +## Group by CPU and time +Group by the `cpu` and `_time` columns. + +```js +dataSet + |> group(columns: ["cpu", "_time"]) +``` + +This outputs a table for every unique `cpu` and `_time` combination: + +{{% truncate %}} +###### Group by CPU and time output tables +``` +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 7.892107892107892 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.7992007992007992 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 4.1 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.5005005005005005 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:10.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 7.2 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:10.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:10.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 3.6 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:10.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.5 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:20.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 7.4 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:20.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:20.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 3.5 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:20.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.5 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:30.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 5.5 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:30.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.4 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:30.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 2.6 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:30.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.3 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:40.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 7.4 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:40.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:40.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 4.5 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:40.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.6 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:50.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 7.5 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:50.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:50.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 4.895104895104895 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:34:50.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.6 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 10.3 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 1.4 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 6.906906906906907 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 1.3986013986013985 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:10.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 9.2 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:10.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 1.2 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:10.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 5.7 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:10.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.9 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:20.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 8.4 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:20.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.8 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:20.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 5.1 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:20.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.5005005005005005 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:30.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 8.5 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:30.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.8991008991008991 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:30.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 4.7 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:30.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.7 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:40.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 8.6 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:40.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.8008008008008008 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:40.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 5.1 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:40.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.6 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:50.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 10.2 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:50.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 0.999000999000999 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:50.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 5.9 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:35:50.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.8 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:36:00.000000000Z cpu0 2018-11-05T21:36:00.000000000Z 10.6 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:36:00.000000000Z cpu1 2018-11-05T21:36:00.000000000Z 1.1022044088176353 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:36:00.000000000Z cpu2 2018-11-05T21:36:00.000000000Z 6.4935064935064934 usage_system cpu 2018-11-05T21:34:00.000000000Z + +Table: keys: [_time, cpu] + _time:time cpu:string _stop:time _value:float _field:string _measurement:string _start:time +------------------------------ ---------------------- ------------------------------ ---------------------------- ---------------------- ---------------------- ------------------------------ +2018-11-05T21:36:00.000000000Z cpu3 2018-11-05T21:36:00.000000000Z 0.9 usage_system cpu 2018-11-05T21:34:00.000000000Z +``` +{{% /truncate %}} + +When visualized, tables appear as individual, unconnected points. + +![Group by CPU and time](/img/flux/grouping-by-cpu-time.png) + +Grouping by `cpu` and `_time` is a good illustration of how grouping works. + +## In conclusion +Grouping is a powerful way to shape your data into your desired output format. +It modifies the group keys of output tables, grouping records into tables that +all share common values within specified columns. diff --git a/content/influxdb/v2.1/query-data/flux/histograms.md b/content/influxdb/v2.1/query-data/flux/histograms.md new file mode 100644 index 0000000000..cf1bdb9626 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/histograms.md @@ -0,0 +1,197 @@ +--- +title: Create histograms with Flux +list_title: Histograms +description: > + Use `histogram()` to create cumulative histograms with Flux. +influxdb/v2.1/tags: [histogram] +menu: + influxdb_2_1: + name: Histograms + parent: Query with Flux +weight: 210 +aliases: + - /influxdb/v2.1/query-data/guides/histograms/ +related: + - /{{< latest "flux" >}}/stdlib/universe/histogram + - /{{< latest "flux" >}}/prometheus/metric-types/histogram/, Work with Prometheus histograms in Flux +list_query_example: histogram +--- + +Histograms provide valuable insight into the distribution of your data. +This guide walks through using Flux's `histogram()` function to transform your data into a **cumulative histogram**. + +If you're just getting started with Flux queries, check out the following: + +- [Get started with Flux](/{{< latest "flux" >}}/get-started/) for a conceptual overview of Flux and parts of a Flux query. +- [Execute queries](/influxdb/v2.1/query-data/execute-queries/) to discover a variety of ways to run your queries. + +## histogram() function + +The [`histogram()` function](/{{< latest "flux" >}}/stdlib/universe/histogram) approximates the +cumulative distribution of a dataset by counting data frequencies for a list of "bins." +A **bin** is simply a range in which a data point falls. +All data points that are less than or equal to the bound are counted in the bin. +In the histogram output, a column is added (`le`) that represents the upper bounds of of each bin. +Bin counts are cumulative. + +```js +from(bucket:"example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> histogram(bins: [0.0, 10.0, 20.0, 30.0]) +``` + +{{% note %}} +Values output by the `histogram` function represent points of data aggregated over time. +Since values do not represent single points in time, there is no `_time` column in the output table. +{{% /note %}} + +## Bin helper functions +Flux provides two helper functions for generating histogram bins. +Each generates an array of floats designed to be used in the `histogram()` function's `bins` parameter. + +### linearBins() +The [`linearBins()` function](/{{< latest "flux" >}}/stdlib/universe/linearbins) generates a list of linearly separated floats. + +```js +linearBins(start: 0.0, width: 10.0, count: 10) + +// Generated list: [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, +Inf] +``` + +### logarithmicBins() +The [`logarithmicBins()` function](/{{< latest "flux" >}}/stdlib/universe/logarithmicbins) generates a list of exponentially separated floats. + +```js +logarithmicBins(start: 1.0, factor: 2.0, count: 10, infinity: true) + +// Generated list: [1, 2, 4, 8, 16, 32, 64, 128, 256, 512, +Inf] +``` + +## Histogram visualization +The [Histogram visualization type](/influxdb/v2.1/visualize-data/visualization-types/histogram/) +automatically converts query results into a binned and segmented histogram. + +{{< img-hd src="/img/influxdb/2-0-visualizations-histogram-example.png" alt="Histogram visualization" />}} + +Use the [Histogram visualization controls](/influxdb/v2.1/visualize-data/visualization-types/histogram/#histogram-controls) +to specify the number of bins and define groups in bins. + +### Histogram visualization data structure +Because the Histogram visualization uses visualization controls to creates bins and groups, +**do not** structure query results as histogram data. + +{{% note %}} +Output of the [`histogram()` function](#histogram-function) is **not** compatible +with the Histogram visualization type. +View the example [below](#visualize-errors-by-severity). +{{% /note %}} + +## Examples + +### Generate a histogram with linear bins +```js +from(bucket:"example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> histogram( + bins: linearBins( + start:65.5, + width: 0.5, + count: 20, + infinity:false + ) + ) +``` + +###### Output table +``` +Table: keys: [_start, _stop, _field, _measurement, host] + _start:time _stop:time _field:string _measurement:string host:string le:float _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------ ---------------------------- ---------------------------- +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 65.5 5 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 66 6 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 66.5 8 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 67 9 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 67.5 9 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 68 10 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 68.5 12 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 69 12 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 69.5 15 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 70 23 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 70.5 30 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 71 30 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 71.5 30 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 72 30 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 72.5 30 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 73 30 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 73.5 30 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 74 30 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 74.5 30 +2018-11-07T22:19:58.423358000Z 2018-11-07T22:24:58.423358000Z used_percent mem Scotts-MacBook-Pro.local 75 30 +``` + +### Generate a histogram with logarithmic bins +```js +from(bucket:"example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> histogram( + bins: logarithmicBins( + start:0.5, + factor: 2.0, + count: 10, + infinity:false + ) + ) +``` + +###### Output table +``` +Table: keys: [_start, _stop, _field, _measurement, host] + _start:time _stop:time _field:string _measurement:string host:string le:float _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------ ---------------------------- ---------------------------- +2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 0.5 0 +2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 1 0 +2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 2 0 +2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 4 0 +2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 8 0 +2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 16 0 +2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 32 0 +2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 64 2 +2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 128 30 +2018-11-07T22:23:36.860664000Z 2018-11-07T22:28:36.860664000Z used_percent mem Scotts-MacBook-Pro.local 256 30 +``` + +### Visualize errors by severity +Use the [Telegraf Syslog plugin](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/syslog) +to collect error information from your system. +Query the `severity_code` field in the `syslog` measurement: + +```js +from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "syslog" and + r._field == "severity_code" + ) +``` + +In the Histogram visualization options, select `_time` as the **X Column** +and `severity` as the **Group By** option: + +{{< img-hd src="/img/influxdb/2-0-visualizations-histogram-errors.png" alt="Logs by severity histogram" />}} + +### Use Prometheus histograms in Flux + +_For information about working with Prometheus histograms in Flux, see +[Work with Prometheus histograms](/{{< latest "flux" >}}/prometheus/metric-types/histogram/)._ \ No newline at end of file diff --git a/content/influxdb/v2.1/query-data/flux/increase.md b/content/influxdb/v2.1/query-data/flux/increase.md new file mode 100644 index 0000000000..238499a3e8 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/increase.md @@ -0,0 +1,57 @@ +--- +title: Calculate the increase +seotitle: Calculate the increase in Flux +list_title: Increase +description: > + Use `increase()` to track increases across multiple columns in a table. + This function is especially useful when tracking changes in counter values that + wrap over time or periodically reset. +weight: 210 +menu: + influxdb_2_1: + parent: Query with Flux + name: Increase +influxdb/v2.1/tags: [query, increase, counters] +related: + - /{{< latest "flux" >}}/stdlib/universe/increase/ +list_query_example: increase +--- + +Use [`increase()`](/{{< latest "flux" >}}/stdlib/universe/increase/) +to track increases across multiple columns in a table. +This function is especially useful when tracking changes in counter values that +wrap over time or periodically reset. + +```js +data + |> increase() +``` + +`increase()` returns a cumulative sum of **non-negative** differences between rows in a table. +For example: + +{{< flex >}} +{{% flex-content %}} +**Given the following input:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:01:00Z | 1 | +| 2020-01-01T00:02:00Z | 2 | +| 2020-01-01T00:03:00Z | 8 | +| 2020-01-01T00:04:00Z | 10 | +| 2020-01-01T00:05:00Z | 0 | +| 2020-01-01T00:06:00Z | 4 | +{{% /flex-content %}} +{{% flex-content %}} +**`increase()` returns:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:02:00Z | 1 | +| 2020-01-01T00:03:00Z | 7 | +| 2020-01-01T00:04:00Z | 9 | +| 2020-01-01T00:05:00Z | 9 | +| 2020-01-01T00:06:00Z | 13 | +{{% /flex-content %}} +{{< /flex >}} diff --git a/content/influxdb/v2.1/query-data/flux/join.md b/content/influxdb/v2.1/query-data/flux/join.md new file mode 100644 index 0000000000..7b641de86c --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/join.md @@ -0,0 +1,315 @@ +--- +title: Join data with Flux +seotitle: Join data in InfluxDB with Flux +list_title: Join +description: This guide walks through joining data with Flux and outlines how it shapes your data in the process. +influxdb/v2.1/tags: [join, flux] +menu: + influxdb_2_1: + name: Join + parent: Query with Flux +weight: 210 +aliases: + - /influxdb/v2.1/query-data/guides/join/ +related: + - /{{< latest "flux" >}}/stdlib/universe/join +list_query_example: join +--- + +The [`join()` function](/{{< latest "flux" >}}/stdlib/universe/join) merges two or more +input streams, whose values are equal on a set of common columns, into a single output stream. +Flux allows you to join on any columns common between two data streams and opens the door +for operations such as cross-measurement joins and math across measurements. + +To illustrate a join operation, use data captured by Telegraf and stored in +InfluxDB - memory usage and processes. + +In this guide, we'll join two data streams, one representing memory usage and the other representing the +total number of running processes, then calculate the average memory usage per running process. + +If you're just getting started with Flux queries, check out the following: + +- [Get started with Flux](/{{< latest "flux" >}}/get-started/) for a conceptual overview of Flux and parts of a Flux query. +- [Execute queries](/influxdb/v2.1/query-data/execute-queries/) to discover a variety of ways to run your queries. + +## Define stream variables +In order to perform a join, you must have two streams of data. +Assign a variable to each data stream. + +### Memory used variable +Define a `memUsed` variable that filters on the `mem` measurement and the `used` field. +This returns the amount of memory (in bytes) used. + +###### memUsed stream definition +```js +memUsed = from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used" + ) +``` + +{{% truncate %}} +###### memUsed data output +``` +Table: keys: [_start, _stop, _field, _measurement, host] + _start:time _stop:time _field:string _measurement:string host:string _time:time _value:int +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------ ------------------------------ -------------------------- +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:50:00.000000000Z 10956333056 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:50:10.000000000Z 11014008832 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:50:20.000000000Z 11373428736 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:50:30.000000000Z 11001421824 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:50:40.000000000Z 10985852928 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:50:50.000000000Z 10992279552 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:51:00.000000000Z 11053568000 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:51:10.000000000Z 11092242432 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:51:20.000000000Z 11612774400 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:51:30.000000000Z 11131961344 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:51:40.000000000Z 11124805632 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:51:50.000000000Z 11332464640 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:52:00.000000000Z 11176923136 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:52:10.000000000Z 11181068288 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:52:20.000000000Z 11182579712 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:52:30.000000000Z 11238862848 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:52:40.000000000Z 11275296768 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:52:50.000000000Z 11225411584 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:53:00.000000000Z 11252690944 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:53:10.000000000Z 11227029504 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:53:20.000000000Z 11201646592 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:53:30.000000000Z 11227897856 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:53:40.000000000Z 11330428928 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:53:50.000000000Z 11347976192 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:54:00.000000000Z 11368271872 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:54:10.000000000Z 11269623808 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:54:20.000000000Z 11295637504 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:54:30.000000000Z 11354423296 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:54:40.000000000Z 11379687424 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:54:50.000000000Z 11248926720 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z used mem host1.local 2018-11-06T05:55:00.000000000Z 11292524544 +``` +{{% /truncate %}} + +### Total processes variable +Define a `procTotal` variable that filters on the `processes` measurement and the `total` field. +This returns the number of running processes. + +###### procTotal stream definition +```js +procTotal = from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => + r._measurement == "processes" and + r._field == "total" + ) +``` + +{{% truncate %}} +###### procTotal data output +``` +Table: keys: [_start, _stop, _field, _measurement, host] + _start:time _stop:time _field:string _measurement:string host:string _time:time _value:int +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------ ------------------------------ -------------------------- +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:50:00.000000000Z 470 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:50:10.000000000Z 470 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:50:20.000000000Z 471 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:50:30.000000000Z 470 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:50:40.000000000Z 469 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:50:50.000000000Z 471 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:51:00.000000000Z 470 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:51:10.000000000Z 470 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:51:20.000000000Z 470 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:51:30.000000000Z 470 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:51:40.000000000Z 469 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:51:50.000000000Z 471 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:52:00.000000000Z 471 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:52:10.000000000Z 470 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:52:20.000000000Z 470 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:52:30.000000000Z 471 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:52:40.000000000Z 472 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:52:50.000000000Z 471 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:53:00.000000000Z 470 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:53:10.000000000Z 470 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:53:20.000000000Z 470 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:53:30.000000000Z 471 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:53:40.000000000Z 471 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:53:50.000000000Z 471 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:54:00.000000000Z 471 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:54:10.000000000Z 470 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:54:20.000000000Z 471 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:54:30.000000000Z 473 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:54:40.000000000Z 471 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:54:50.000000000Z 471 +2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z total processes host1.local 2018-11-06T05:55:00.000000000Z 471 +``` +{{% /truncate %}} + +## Join the two data streams +With the two data streams defined, use the `join()` function to join them together. +`join()` requires two parameters: + +##### `tables` +A map of tables to join with keys by which they will be aliased. +In the example below, `mem` is the alias for `memUsed` and `proc` is the alias for `procTotal`. + +##### `on` +An array of strings defining the columns on which the tables will be joined. +_**Both tables must have all columns specified in this list.**_ + +```js +join( + tables: {mem:memUsed, proc:procTotal}, + on: ["_time", "_stop", "_start", "host"] +) +``` + +{{% truncate %}} +###### Joined output table +``` +Table: keys: [_field_mem, _field_proc, _measurement_mem, _measurement_proc, _start, _stop, host] + _field_mem:string _field_proc:string _measurement_mem:string _measurement_proc:string _start:time _stop:time host:string _time:time _value_mem:int _value_proc:int +---------------------- ---------------------- ----------------------- ------------------------ ------------------------------ ------------------------------ ------------------------ ------------------------------ -------------------------- -------------------------- + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:50:00.000000000Z 10956333056 470 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:50:10.000000000Z 11014008832 470 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:50:20.000000000Z 11373428736 471 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:50:30.000000000Z 11001421824 470 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:50:40.000000000Z 10985852928 469 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:50:50.000000000Z 10992279552 471 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:51:00.000000000Z 11053568000 470 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:51:10.000000000Z 11092242432 470 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:51:20.000000000Z 11612774400 470 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:51:30.000000000Z 11131961344 470 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:51:40.000000000Z 11124805632 469 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:51:50.000000000Z 11332464640 471 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:52:00.000000000Z 11176923136 471 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:52:10.000000000Z 11181068288 470 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:52:20.000000000Z 11182579712 470 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:52:30.000000000Z 11238862848 471 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:52:40.000000000Z 11275296768 472 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:52:50.000000000Z 11225411584 471 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:53:00.000000000Z 11252690944 470 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:53:10.000000000Z 11227029504 470 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:53:20.000000000Z 11201646592 470 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:53:30.000000000Z 11227897856 471 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:53:40.000000000Z 11330428928 471 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:53:50.000000000Z 11347976192 471 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:54:00.000000000Z 11368271872 471 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:54:10.000000000Z 11269623808 470 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:54:20.000000000Z 11295637504 471 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:54:30.000000000Z 11354423296 473 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:54:40.000000000Z 11379687424 471 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:54:50.000000000Z 11248926720 471 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:55:00.000000000Z 11292524544 471 +``` +{{% /truncate %}} + +Notice the output table includes the following columns: + +- `_field_mem` +- `_field_proc` +- `_measurement_mem` +- `_measurement_proc` +- `_value_mem` +- `_value_proc` + +These represent the columns with values unique to the two input tables. + +## Calculate and create a new table +With the two streams of data joined into a single table, use the +[`map()` function](/{{< latest "flux" >}}/stdlib/universe/map) +to build a new table by mapping the existing `_time` column to a new `_time` +column and dividing `_value_mem` by `_value_proc` and mapping it to a +new `_value` column. + +```js +join(tables: {mem:memUsed, proc:procTotal}, on: ["_time", "_stop", "_start", "host"]) + |> map(fn: (r) => ({ + _time: r._time, + _value: r._value_mem / r._value_proc + }) + ) +``` + +{{% truncate %}} +###### Mapped table +``` +Table: keys: [_field_mem, _field_proc, _measurement_mem, _measurement_proc, _start, _stop, host] + _field_mem:string _field_proc:string _measurement_mem:string _measurement_proc:string _start:time _stop:time host:string _time:time _value:int +---------------------- ---------------------- ----------------------- ------------------------ ------------------------------ ------------------------------ ------------------------ ------------------------------ -------------------------- + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:50:00.000000000Z 23311346 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:50:10.000000000Z 23434061 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:50:20.000000000Z 24147407 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:50:30.000000000Z 23407280 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:50:40.000000000Z 23423993 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:50:50.000000000Z 23338173 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:51:00.000000000Z 23518229 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:51:10.000000000Z 23600515 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:51:20.000000000Z 24708030 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:51:30.000000000Z 23685024 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:51:40.000000000Z 23720267 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:51:50.000000000Z 24060434 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:52:00.000000000Z 23730197 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:52:10.000000000Z 23789506 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:52:20.000000000Z 23792722 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:52:30.000000000Z 23861704 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:52:40.000000000Z 23888340 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:52:50.000000000Z 23833145 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:53:00.000000000Z 23941895 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:53:10.000000000Z 23887296 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:53:20.000000000Z 23833290 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:53:30.000000000Z 23838424 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:53:40.000000000Z 24056112 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:53:50.000000000Z 24093367 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:54:00.000000000Z 24136458 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:54:10.000000000Z 23977922 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:54:20.000000000Z 23982245 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:54:30.000000000Z 24005123 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:54:40.000000000Z 24160695 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:54:50.000000000Z 23883071 + used total mem processes 2018-11-06T05:50:00.000000000Z 2018-11-06T05:55:00.000000000Z Scotts-MacBook-Pro.local 2018-11-06T05:55:00.000000000Z 23975635 +``` +{{% /truncate %}} + +This table represents the average amount of memory in bytes per running process. + + +## Real world example +The following function calculates the batch sizes written to an InfluxDB cluster by joining +fields from `httpd` and `write` measurements in order to compare `pointReq` and `writeReq`. +The results are grouped by cluster ID so you can make comparisons across clusters. + +```js +batchSize = (cluster_id, start=-1m, interval=10s) => { + httpd = from(bucket:"telegraf") + |> range(start:start) + |> filter(fn:(r) => + r._measurement == "influxdb_httpd" and + r._field == "writeReq" and + r.cluster_id == cluster_id + ) + |> aggregateWindow(every: interval, fn: mean) + |> derivative(nonNegative:true,unit:60s) + + write = from(bucket:"telegraf") + |> range(start:start) + |> filter(fn:(r) => + r._measurement == "influxdb_write" and + r._field == "pointReq" and + r.cluster_id == cluster_id + ) + |> aggregateWindow(every: interval, fn: max) + |> derivative(nonNegative:true,unit:60s) + + return join( + tables:{httpd:httpd, write:write}, + on:["_time","_stop","_start","host"] + ) + |> map(fn:(r) => ({ + _time: r._time, + _value: r._value_httpd / r._value_write, + })) + |> group(columns: cluster_id) +} + +batchSize(cluster_id: "enter cluster id here") +``` diff --git a/content/influxdb/v2.1/query-data/flux/manipulate-timestamps.md b/content/influxdb/v2.1/query-data/flux/manipulate-timestamps.md new file mode 100644 index 0000000000..c51e4e7fe0 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/manipulate-timestamps.md @@ -0,0 +1,218 @@ +--- +title: Manipulate timestamps with Flux +list_title: Manipulate timestamps +description: > + Use Flux to process and manipulate timestamps. +menu: + influxdb_2_1: + name: Manipulate timestamps + parent: Query with Flux +weight: 220 +aliases: + - /influxdb/v2.1/query-data/guides/manipulate-timestamps/ +related: + - /{{< latest "flux" >}}/stdlib/universe/now/ + - /{{< latest "flux" >}}/stdlib/system/time/ + - /{{< latest "flux" >}}/stdlib/universe/time/ + - /{{< latest "flux" >}}/stdlib/universe/uint/ + - /{{< latest "flux" >}}/stdlib/universe/int/ + - /{{< latest "flux" >}}/stdlib/universe/truncatetimecolumn/ + - /{{< latest "flux" >}}/stdlib/date/truncate/ + - /{{< latest "flux" >}}/stdlib/experimental/addduration/ + - /{{< latest "flux" >}}/stdlib/experimental/subduration/ +--- + +Every point stored in InfluxDB has an associated timestamp. +Use Flux to process and manipulate timestamps to suit your needs. + +- [Convert timestamp format](#convert-timestamp-format) +- [Calculate the duration between two timestamps](#calculate-the-duration-between-two-timestamps) +- [Retrieve the current time](#retrieve-the-current-time) +- [Normalize irregular timestamps](#normalize-irregular-timestamps) +- [Use timestamps and durations together](#use-timestamps-and-durations-together) + +{{% note %}} +If you're just getting started with Flux queries, check out the following: + +- [Get started with Flux](/{{< latest "flux" >}}/get-started/) for a conceptual overview of Flux and parts of a Flux query. +- [Execute queries](/influxdb/v2.1/query-data/execute-queries/) to discover a variety of ways to run your queries. +{{% /note %}} + + +## Convert timestamp format + +- [Unix nanosecond to RFC3339](#unix-nanosecond-to-rfc3339) +- [RFC3339 to Unix nanosecond](#rfc3339-to-unix-nanosecond) + +### Unix nanosecond to RFC3339 +Use the [`time()` function](/{{< latest "flux" >}}/stdlib/universe/time/) +to convert a [Unix **nanosecond** timestamp](/influxdb/v2.1/reference/glossary/#unix-timestamp) +to an [RFC3339 timestamp](/influxdb/v2.1/reference/glossary/#rfc3339-timestamp). + +```js +time(v: 1568808000000000000) +// Returns 2019-09-18T12:00:00.000000000Z +``` + +### RFC3339 to Unix nanosecond +Use the [`uint()` function](/{{< latest "flux" >}}/stdlib/universe/uint/) +to convert an RFC3339 timestamp to a Unix nanosecond timestamp. + +```js +uint(v: 2019-09-18T12:00:00.000000000Z) +// Returns 1568808000000000000 +``` + +## Calculate the duration between two timestamps +Flux doesn't support mathematical operations using [time type](/{{< latest "flux" >}}/spec/types/#time-types) values. +To calculate the duration between two timestamps: + +1. Use the `uint()` function to convert each timestamp to a Unix nanosecond timestamp. +2. Subtract one Unix nanosecond timestamp from the other. +3. Use the `duration()` function to convert the result into a duration. + +```js +time1 = uint(v: 2019-09-17T21:12:05Z) +time2 = uint(v: 2019-09-18T22:16:35Z) + +duration(v: time2 - time1) +// Returns 25h4m30s +``` + +{{% note %}} +Flux doesn't support duration column types. +To store a duration in a column, use the [`string()` function](/{{< latest "flux" >}}/stdlib/universe/string/) +to convert the duration to a string. +{{% /note %}} + +## Retrieve the current time +- [Current UTC time](#current-utc-time) +- [Current system time](#current-system-time) + +### Current UTC time +Use the [`now()` function](/{{< latest "flux" >}}/stdlib/universe/now/) to +return the current UTC time in RFC3339 format. + +```js +now() +``` + +{{% note %}} +`now()` is cached at runtime, so all instances of `now()` in a Flux script +return the same value. +{{% /note %}} + +### Current system time +Import the `system` package and use the [`system.time()` function](/{{< latest "flux" >}}/stdlib/system/time/) +to return the current system time of the host machine in RFC3339 format. + +```js +import "system" + +system.time() +``` + +{{% note %}} +`system.time()` returns the time it is executed, so each instance of `system.time()` +in a Flux script returns a unique value. +{{% /note %}} + +## Normalize irregular timestamps +To normalize irregular timestamps, truncate all `_time` values to a specified unit +with the [`truncateTimeColumn()` function](/{{< latest "flux" >}}/stdlib/universe/truncatetimecolumn/). +This is useful in [`join()`](/{{< latest "flux" >}}/stdlib/universe/join/) +and [`pivot()`](/{{< latest "flux" >}}/stdlib/universe/pivot/) +operations where points should align by time, but timestamps vary slightly. + +```js +data + |> truncateTimeColumn(unit: 1m) +``` + +{{< flex >}} +{{% flex-content %}} +**Input:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:00:49Z | 2.0 | +| 2020-01-01T00:01:01Z | 1.9 | +| 2020-01-01T00:03:22Z | 1.8 | +| 2020-01-01T00:04:04Z | 1.9 | +| 2020-01-01T00:05:38Z | 2.1 | +{{% /flex-content %}} +{{% flex-content %}} +**Output:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:00:00Z | 2.0 | +| 2020-01-01T00:01:00Z | 1.9 | +| 2020-01-01T00:03:00Z | 1.8 | +| 2020-01-01T00:04:00Z | 1.9 | +| 2020-01-01T00:05:00Z | 2.1 | +{{% /flex-content %}} +{{< /flex >}} + +## Use timestamps and durations together +- [Add a duration to a timestamp](#add-a-duration-to-a-timestamp) +- [Subtract a duration from a timestamp](#subtract-a-duration-from-a-timestamp) + +### Add a duration to a timestamp +The [`experimental.addDuration()` function](/{{< latest "flux" >}}/stdlib/experimental/to/addduration/) +adds a duration to a specified time and returns the resulting time. + +{{% warn %}} +By using `experimental.addDuration()`, you accept the +[risks of experimental functions](/{{< latest "flux" >}}/stdlib/experimental/to/#experimental-functions-are-subject-to-change). +{{% /warn %}} + +```js +import "experimental" + +experimental.addDuration( + d: 6h, + to: 2019-09-16T12:00:00Z, +) + +// Returns 2019-09-16T18:00:00.000000000Z +``` + +### Subtract a duration from a timestamp +The [`experimental.subDuration()` function](/{{< latest "flux" >}}/stdlib/experimental/to/subduration/) +subtracts a duration from a specified time and returns the resulting time. + +{{% warn %}} +By using `experimental.subDuration()`, you accept the +[risks of experimental functions](/{{< latest "flux" >}}/stdlib/experimental/to/#experimental-functions-are-subject-to-change). +{{% /warn %}} + +```js +import "experimental" + +experimental.subDuration( + d: 6h, + from: 2019-09-16T12:00:00Z, +) + +// Returns 2019-09-16T06:00:00.000000000Z +``` + +### Shift a timestamp forward or backward + +The [timeShift()](/{{< latest "flux" >}}/stdlib/universe/timeshift/) function adds the specified duration of time to each value in time columns (`_start`, `_stop`, `_time`). + +Shift forward in time: + +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> timeShift(duration: 12h) +``` +Shift backward in time: + +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> timeShift(duration: -12h) +``` diff --git a/content/influxdb/v2.1/query-data/flux/mathematic-operations.md b/content/influxdb/v2.1/query-data/flux/mathematic-operations.md new file mode 100644 index 0000000000..e3a149906a --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/mathematic-operations.md @@ -0,0 +1,235 @@ +--- +title: Transform data with mathematic operations +seotitle: Transform data with mathematic operations in Flux +list_title: Transform data with math +description: > + Use `map()` to remap column values and apply mathematic operations. +influxdb/v2.1/tags: [math, flux] +menu: + influxdb_2_1: + name: Transform data with math + parent: Query with Flux +weight: 208 +aliases: + - /influxdb/v2.1/query-data/guides/mathematic-operations/ +related: + - /{{< latest "flux" >}}/stdlib/universe/map + - /{{< latest "flux" >}}/stdlib/universe/aggregates/reduce/ + - /{{< latest "flux" >}}/language/operators/ + - /{{< latest "flux" >}}/function-types/#type-conversions, Flux type-conversion functions + - /influxdb/v2.1/query-data/flux/calculate-percentages/ +list_query_example: map_math +--- + +[Flux](/{{< latest "flux" >}}/), InfluxData's data scripting and query language, +supports mathematic expressions in data transformations. +This article describes how to use [Flux arithmetic operators](/{{< latest "flux" >}}/spec/operators/#arithmetic-operators) +to "map" over data and transform values using mathematic operations. + +If you're just getting started with Flux queries, check out the following: + +- [Get started with Flux](/{{< latest "flux" >}}/get-started/) for a conceptual overview of Flux and parts of a Flux query. +- [Execute queries](/influxdb/v2.1/query-data/execute-queries/) to discover a variety of ways to run your queries. + +##### Basic mathematic operations +```js +// Examples executed using the Flux REPL +> 9 + 9 +18 +> 22 - 14 +8 +> 6 * 5 +30 +> 21 / 7 +3 +``` + +

    See Flux Read-Eval-Print Loop (REPL).

    + +{{% note %}} +#### Operands must be the same type +Operands in Flux mathematic operations must be the same data type. +For example, integers cannot be used in operations with floats. +Otherwise, you will get an error similar to: + +``` +Error: type error: float != int +``` + +To convert operands to the same type, use [type-conversion functions](/{{< latest "flux" >}}/stdlib/universe/) +or manually format operands. +The operand data type determines the output data type. +For example: + +```js +100 // Parsed as an integer +100.0 // Parsed as a float + +// Example evaluations +> 20 / 8 +2 + +> 20.0 / 8.0 +2.5 +``` +{{% /note %}} + +## Custom mathematic functions +Flux lets you [create custom functions](/influxdb/v2.1/query-data/flux/custom-functions) that use mathematic operations. +View the examples below. + +###### Custom multiplication function +```js +multiply = (x, y) => x * y + +multiply(x: 10, y: 12) +// Returns 120 +``` + +###### Custom percentage function +```js +percent = (sample, total) => (sample / total) * 100.0 + +percent(sample: 20.0, total: 80.0) +// Returns 25.0 +``` + +### Transform values in a data stream +To transform multiple values in an input stream, your function needs to: + +- [Handle piped-forward data](/influxdb/v2.1/query-data/flux/custom-functions/#use-piped-forward-data-in-a-custom-function). +- Each operand necessary for the calculation exists in each row _(see [Pivot vs join](#pivot-vs-join) below)_. +- Use the [`map()` function](/{{< latest "flux" >}}/stdlib/universe/map) to iterate over each row. + +The example `multiplyByX()` function below includes: + +- A `tables` parameter that represents the input data stream (`<-`). +- An `x` parameter which is the number by which values in the `_value` column are multiplied. +- A `map()` function that iterates over each row in the input stream. + It uses the `with` operator to preserve existing columns in each row. + It also multiples the `_value` column by `x`. + +```js +multiplyByX = (x, tables=<-) => + tables + |> map(fn: (r) => ({ + r with + _value: r._value * x + }) + ) + +data + |> multiplyByX(x: 10) +``` + +## Examples + +### Convert bytes to gigabytes +To convert active memory from bytes to gigabytes (GB), divide the `active` field +in the `mem` measurement by 1,073,741,824. + +The `map()` function iterates over each row in the piped-forward data and defines +a new `_value` by dividing the original `_value` by 1073741824. + +```js +from(bucket: "example-bucket") + |> range(start: -10m) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "active" + ) + |> map(fn: (r) => ({ + r with + _value: r._value / 1073741824 + }) + ) +``` + +You could turn that same calculation into a function: + +```js +bytesToGB = (tables=<-) => + tables + |> map(fn: (r) => ({ + r with + _value: r._value / 1073741824 + }) + ) + +data + |> bytesToGB() +``` + +#### Include partial gigabytes +Because the original metric (bytes) is an integer, the output of the operation is an integer and does not include partial GBs. +To calculate partial GBs, convert the `_value` column and its values to floats using the +[`float()` function](/{{< latest "flux" >}}/stdlib/universe/float) +and format the denominator in the division operation as a float. + +```js +bytesToGB = (tables=<-) => + tables + |> map(fn: (r) => ({ + r with + _value: float(v: r._value) / 1073741824.0 + }) + ) +``` + +### Calculate a percentage +To calculate a percentage, use simple division, then multiply the result by 100. + +```js +> 1.0 / 4.0 * 100.0 +25.0 +``` + +_For an in-depth look at calculating percentages, see [Calculate percentages](/influxdb/v2.1/query-data/flux/calculate-percentages)._ + +## Pivot vs join +To query and use values in mathematical operations in Flux, operand values must +exists in a single row. +Both `pivot()` and `join()` will do this, but there are important differences between the two: + +#### Pivot is more performant +`pivot()` reads and operates on a single stream of data. +`join()` requires two streams of data and the overhead of reading and combining +both streams can be significant, especially for larger data sets. + +#### Use join for multiple data sources +Use `join()` when querying data from different buckets or data sources. + +##### Pivot fields into columns for mathematic calculations +```js +data + |> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") + |> map(fn: (r) => ({ r with + _value: (r.field1 + r.field2) / r.field3 * 100.0 + })) +``` + +##### Join multiple data sources for mathematic calculations +```js +import "sql" +import "influxdata/influxdb/secrets" + +pgUser = secrets.get(key: "POSTGRES_USER") +pgPass = secrets.get(key: "POSTGRES_PASSWORD") +pgHost = secrets.get(key: "POSTGRES_HOST") + +t1 = sql.from( + driverName: "postgres", + dataSourceName: "postgresql://${pgUser}:${pgPass}@${pgHost}", + query:"SELECT id, name, available FROM example_table" +) + +t2 = from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "example-measurement" and + r._field == "example-field" + ) + +join(tables: {t1: t1, t2: t2}, on: ["id"]) + |> map(fn: (r) => ({ r with _value: r._value_t2 / r.available_t1 * 100.0 })) +``` diff --git a/content/influxdb/v2.1/query-data/flux/median.md b/content/influxdb/v2.1/query-data/flux/median.md new file mode 100644 index 0000000000..aa44f8eebd --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/median.md @@ -0,0 +1,149 @@ +--- +title: Find median values +seotitle: Find median values in Flux +list_title: Median +description: > + Use `median()` to return a value representing the `0.5` quantile (50th percentile) or median of input data. +weight: 210 +menu: + influxdb_2_1: + parent: Query with Flux + name: Median +influxdb/v2.1/tags: [query, median] +related: + - /influxdb/v2.1/query-data/flux/percentile-quantile/ + - /{{< latest "flux" >}}/stdlib/universe/median/ + - /{{< latest "flux" >}}/stdlib/universe/quantile/ +list_query_example: median +--- + +Use the [`median()` function](/{{< latest "flux" >}}/stdlib/universe/median/) +to return a value representing the `0.5` quantile (50th percentile) or median of input data. + +## Select a method for calculating the median +Select one of the following methods to calculate the median: + +- [estimate_tdigest](#estimate_tdigest) +- [exact_mean](#exact_mean) +- [exact_selector](#exact_selector) + +### estimate_tdigest +**(Default)** An aggregate method that uses a [t-digest data structure](https://github.com/tdunning/t-digest) +to compute an accurate `0.5` quantile estimate on large data sources. +Output tables consist of a single row containing the calculated median. + +{{< flex >}} +{{% flex-content %}} +**Given the following input table:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:01:00Z | 1.0 | +| 2020-01-01T00:02:00Z | 1.0 | +| 2020-01-01T00:03:00Z | 2.0 | +| 2020-01-01T00:04:00Z | 3.0 | +{{% /flex-content %}} +{{% flex-content %}} +**`estimate_tdigest` returns:** + +| _value | +|:------:| +| 1.5 | +{{% /flex-content %}} +{{< /flex >}} + +### exact_mean +An aggregate method that takes the average of the two points closest to the `0.5` quantile value. +Output tables consist of a single row containing the calculated median. + +{{< flex >}} +{{% flex-content %}} +**Given the following input table:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:01:00Z | 1.0 | +| 2020-01-01T00:02:00Z | 1.0 | +| 2020-01-01T00:03:00Z | 2.0 | +| 2020-01-01T00:04:00Z | 3.0 | +{{% /flex-content %}} +{{% flex-content %}} +**`exact_mean` returns:** + +| _value | +|:------:| +| 1.5 | +{{% /flex-content %}} +{{< /flex >}} + +### exact_selector +A selector method that returns the data point for which at least 50% of points are less than. +Output tables consist of a single row containing the calculated median. + +{{< flex >}} +{{% flex-content %}} +**Given the following input table:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:01:00Z | 1.0 | +| 2020-01-01T00:02:00Z | 1.0 | +| 2020-01-01T00:03:00Z | 2.0 | +| 2020-01-01T00:04:00Z | 3.0 | +{{% /flex-content %}} +{{% flex-content %}} +**`exact_selector` returns:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:02:00Z | 1.0 | +{{% /flex-content %}} +{{< /flex >}} + +{{% note %}} +The examples below use the [example data variable](/influxdb/v2.1/query-data/flux/#example-data-variable). +{{% /note %}} + +## Find the value that represents the median +Use the default method, `"estimate_tdigest"`, to return all rows in a table that +contain values in the 50th percentile of data in the table. + +```js +data + |> median() +``` + +## Find the average of values closest to the median +Use the `exact_mean` method to return a single row per input table containing the +average of the two values closest to the mathematical median of data in the table. + +```js +data + |> median(method: "exact_mean") +``` + +## Find the point with the median value +Use the `exact_selector` method to return a single row per input table containing the +value that 50% of values in the table are less than. + +```js +data + |> median(method: "exact_selector") +``` + +## Use median() with aggregateWindow() +[`aggregateWindow()`](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow/) +segments data into windows of time, aggregates data in each window into a single +point, and then removes the time-based segmentation. +It is primarily used to [downsample data](/influxdb/v2.1/process-data/common-tasks/downsample-data/). + +To specify the [median calculation method](#select-a-method-for-calculating-the-median) in `aggregateWindow()`, use the +[full function syntax](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow/#specify-parameters-of-the-aggregate-function): + +```js +data + |> aggregateWindow( + every: 5m, + fn: (tables=<-, column) => tables |> median(method: "exact_selector") + ) +``` diff --git a/content/influxdb/v2.1/query-data/flux/monitor-states.md b/content/influxdb/v2.1/query-data/flux/monitor-states.md new file mode 100644 index 0000000000..af01694ef2 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/monitor-states.md @@ -0,0 +1,199 @@ +--- +title: Monitor states +seotitle: Monitor states and state changes in your events and metrics with Flux. +description: Flux provides several functions to help monitor states and state changes in your data. +influxdb/v2.1/tags: [states, monitor, flux] +menu: + influxdb_2_1: + name: Monitor states + parent: Query with Flux +weight: 220 +aliases: + - /influxdb/v2.1/query-data/guides/monitor-states/ +related: + - /{{< latest "flux" >}}/stdlib/universe/stateduration/ + - /{{< latest "flux" >}}/stdlib/universe/statecount/ +--- + +Flux helps you monitor states in your metrics and events: + +- [Find how long a state persists](#find-how-long-a-state-persists) +- [Count the number of consecutive states](#count-the-number-of-consecutive-states) + + +If you're just getting started with Flux queries, check out the following: + +- [Get started with Flux](/{{< latest "flux" >}}/get-started/) for a conceptual overview of Flux. +- [Execute queries](/influxdb/v2.1/query-data/execute-queries/) to discover a variety of ways to run your queries. + +## Find how long a state persists + +1. Use the [`stateDuration()`](/{{< latest "flux" >}}/stdlib/universe/stateduration/) function to calculate how long a column value has remained the same value (or state). Include the following information: + + - **Column to search:** any tag key, tag value, field key, field value, or measurement. + - **Value:** the value (or state) to search for in the specified column. + - **State duration column:** a new column to store the state duration─the length of time that the specified value persists. + - **Unit:** the unit of time (`1s` (by default), `1m`, `1h`) used to increment the state duration. + + ```js + |> stateDuration( + fn: (r) => r._column_to_search == "value_to_search_for", + column: "state_duration", + unit: 1s + ) + ``` + +2. Use `stateDuration()` to search each point for the specified value: + + - For the first point that evaluates `true`, the state duration is set to `0`. For each consecutive point that evaluates `true`, the state duration increases by the time interval between each consecutive point (in specified units). + - If the state is `false`, the state duration is reset to `-1`. + +### Example query with stateDuration() + +The following query searches the `doors` bucket over the past 5 minutes to find how many seconds a door has been `closed`. + +```js + from(bucket: "doors") + |> range(start: -5m) + |> stateDuration( + fn: (r) => + r._value == "closed", + column: "door_closed", + unit: 1s) +``` + +In this example, `door_closed` is the **State duration** column. If you write data to the `doors` bucket every minute, the state duration increases by `60s` for each consecutive point where `_value` is `closed`. If `_value` is not `closed`, the state duration is reset to `0`. + +#### Query results + +Results for the example query above may look like this (for simplicity, we've omitted the measurement, tag, and field columns): + +```sh +_time _value door_closed +2019-10-26T17:39:16Z closed 0 +2019-10-26T17:40:16Z closed 60 +2019-10-26T17:41:16Z closed 120 +2019-10-26T17:42:16Z open -1 +2019-10-26T17:43:16Z closed 0 +2019-10-26T17:44:27Z closed 60 +``` + +## Count the number of consecutive states + +1. Use the [`stateCount()` function](/{{< latest "flux" >}}/stdlib/universe/statecount/) + and include the following information: + + - **Column to search:** any tag key, tag value, field key, field value, or measurement. + - **Value:** to search for in the specified column. + - **State count column:** a new column to store the state count─the number of + consecutive records in which the specified value exists. + + ```js + |> stateCount( + fn: (r) => r._column_to_search == "value_to_search_for", + column: "state_count" + ) + ``` + +2. Use `stateCount()` to search each point for the specified value: + + - For the first point that evaluates `true`, the state count is set to `1`. For each consecutive point that evaluates `true`, the state count increases by 1. + - If the state is `false`, the state count is reset to `-1`. + +### Example query with stateCount() + +The following query searches the `doors` bucket over the past 5 minutes and calculates how many points have `closed` as their `_value`. + +```js +from(bucket: "doors") + |> range(start: -5m) + |> stateDuration( + fn: (r) => r._value == "closed", + column: "door_closed" + ) +``` + +This example stores the **state count** in the `door_closed` column. If you write data to the `doors` bucket every minute, the state count increases by `1` for each consecutive point where `_value` is `closed`. If `_value` is not `closed`, the state count is reset to `-1`. + +#### Query results + +Results for the example query above may look like this (for simplicity, we've omitted the measurement, tag, and field columns): + +```bash +_time _value door_closed +2019-10-26T17:39:16Z closed 1 +2019-10-26T17:40:16Z closed 2 +2019-10-26T17:41:16Z closed 3 +2019-10-26T17:42:16Z open -1 +2019-10-26T17:43:16Z closed 1 +2019-10-26T17:44:27Z closed 2 +``` + +#### Example query to count machine state + +The following query checks the machine state every minute (idle, assigned, or busy). InfluxDB searches the `servers` bucket over the past hour and counts records with a machine state of `idle`, `assigned` or `busy`. + +```js +from(bucket: "servers") + |> range(start: -1h) + |> filter(fn: (r) => + r.machine_state == "idle" or + r.machine_state == "assigned" or + r.machine_state == "busy" + ) + |> stateCount(fn: (r) => r.machine_state == "busy", column: "_count") + |> stateCount(fn: (r) => r.machine_state == "assigned", column: "_count") + |> stateCount(fn: (r) => r.machine_state == "idle", column: "_count") +``` + + + + diff --git a/content/influxdb/v2.1/query-data/flux/moving-average.md b/content/influxdb/v2.1/query-data/flux/moving-average.md new file mode 100644 index 0000000000..1f71026255 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/moving-average.md @@ -0,0 +1,121 @@ +--- +title: Calculate the moving average +seotitle: Calculate the moving average in Flux +list_title: Moving Average +description: > + Use `movingAverage()` or `timedMovingAverage()` to return the moving average of data. +weight: 210 +menu: + influxdb_2_1: + parent: Query with Flux + name: Moving Average +influxdb/v2.1/tags: [query, moving average] +related: + - /{{< latest "flux" >}}/stdlib/universe/movingaverage/ + - /{{< latest "flux" >}}/stdlib/universe/timedmovingaverage/ +list_query_example: moving_average +--- + +Use [`movingAverage()`](/{{< latest "flux" >}}/stdlib/universe/movingaverage/) +or [`timedMovingAverage()`](/{{< latest "flux" >}}/stdlib/universe/timedmovingaverage/) +to return the moving average of data. + +```js +data + |> movingAverage(n: 5) + +// OR + +data + |> timedMovingAverage(every: 5m, period: 10m) +``` + +### movingAverage() +For each row in a table, `movingAverage()` returns the average of the current value and +**previous** values where `n` is the total number of values used to calculate the average. + +If `n = 3`: + +| Row # | Calculation | +|:-----:|:----------- | +| 1 | _Insufficient number of rows_ | +| 2 | _Insufficient number of rows_ | +| 3 | (Row1 + Row2 + Row3) / 3 | +| 4 | (Row2 + Row3 + Row4) / 3 | +| 5 | (Row3 + Row4 + Row5) / 3 | + +{{< flex >}} +{{% flex-content %}} +**Given the following input:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:01:00Z | 1.0 | +| 2020-01-01T00:02:00Z | 1.2 | +| 2020-01-01T00:03:00Z | 1.8 | +| 2020-01-01T00:04:00Z | 0.9 | +| 2020-01-01T00:05:00Z | 1.4 | +| 2020-01-01T00:06:00Z | 2.0 | +{{% /flex-content %}} +{{% flex-content %}} +**The following would return:** + +```js +|> movingAverage(n: 3) +``` + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:03:00Z | 1.33 | +| 2020-01-01T00:04:00Z | 1.30 | +| 2020-01-01T00:05:00Z | 1.36 | +| 2020-01-01T00:06:00Z | 1.43 | +{{% /flex-content %}} +{{< /flex >}} + +### timedMovingAverage() +For each row in a table, `timedMovingAverage()` returns the average of the +current value and all row values in the **previous** `period` (duration). +It returns moving averages at a frequency defined by the `every` parameter. + +Each color in the diagram below represents a period of time used to calculate an +average and the time a point representing the average is returned. +If `every = 30m` and `period = 1h`: + +{{< svg "/static/svgs/timed-moving-avg.svg" >}} + +{{< flex >}} +{{% flex-content %}} +**Given the following input:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:00:00Z | 1.0 | +| 2020-01-01T00:30:00Z | 1.2 | +| 2020-01-01T01:00:00Z | 1.8 | +| 2020-01-01T01:30:00Z | 0.9 | +| 2020-01-01T02:00:00Z | 1.4 | +| 2020-01-01T02:30:00Z | 2.0 | +| 2020-01-01T03:00:00Z | 1.9 | +{{% /flex-content %}} +{{% flex-content %}} +**The following would return:** + +```js +|> timedMovingAverage( + every: 30m, + period: 1h +) +``` + +| _time | _value | +| :------------------- | -----: | +| 2020-01-01T00:30:00Z | 1.0 | +| 2020-01-01T01:00:00Z | 1.1 | +| 2020-01-01T01:30:00Z | 1.5 | +| 2020-01-01T02:00:00Z | 1.35 | +| 2020-01-01T02:30:00Z | 1.15 | +| 2020-01-01T03:00:00Z | 1.7 | +| 2020-01-01T03:00:00Z | 2 | +{{% /flex-content %}} +{{< /flex >}} diff --git a/content/influxdb/v2.1/query-data/flux/percentile-quantile.md b/content/influxdb/v2.1/query-data/flux/percentile-quantile.md new file mode 100644 index 0000000000..a49fecb89e --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/percentile-quantile.md @@ -0,0 +1,165 @@ +--- +title: Find percentile and quantile values +seotitle: Query percentile and quantile values in Flux +list_title: Percentile & quantile +description: > + Use the `quantile()` function to return all values within the `q` quantile or + percentile of input data. +weight: 210 +menu: + influxdb_2_1: + parent: Query with Flux + name: Percentile & quantile +influxdb/v2.1/tags: [query, percentile, quantile] +related: + - /influxdb/v2.1/query-data/flux/query-median/ + - /{{< latest "flux" >}}/stdlib/universe/quantile/ +list_query_example: quantile +--- + +Use the [`quantile()` function](/{{< latest "flux" >}}/stdlib/universe/quantile/) +to return a value representing the `q` quantile or percentile of input data. + +## Percentile versus quantile +Percentiles and quantiles are very similar, differing only in the number used to calculate return values. +A percentile is calculated using numbers between `0` and `100`. +A quantile is calculated using numbers between `0.0` and `1.0`. +For example, the **`0.5` quantile** is the same as the **50th percentile**. + +## Select a method for calculating the quantile +Select one of the following methods to calculate the quantile: + +- [estimate_tdigest](#estimate_tdigest) +- [exact_mean](#exact_mean) +- [exact_selector](#exact_selector) + +### estimate_tdigest +**(Default)** An aggregate method that uses a [t-digest data structure](https://github.com/tdunning/t-digest) +to compute a quantile estimate on large data sources. +Output tables consist of a single row containing the calculated quantile. + +If calculating the `0.5` quantile or 50th percentile: + +{{< flex >}} +{{% flex-content %}} +**Given the following input table:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:01:00Z | 1.0 | +| 2020-01-01T00:02:00Z | 1.0 | +| 2020-01-01T00:03:00Z | 2.0 | +| 2020-01-01T00:04:00Z | 3.0 | +{{% /flex-content %}} +{{% flex-content %}} +**`estimate_tdigest` returns:** + +| _value | +|:------:| +| 1.5 | +{{% /flex-content %}} +{{< /flex >}} + +### exact_mean +An aggregate method that takes the average of the two points closest to the quantile value. +Output tables consist of a single row containing the calculated quantile. + +If calculating the `0.5` quantile or 50th percentile: + +{{< flex >}} +{{% flex-content %}} +**Given the following input table:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:01:00Z | 1.0 | +| 2020-01-01T00:02:00Z | 1.0 | +| 2020-01-01T00:03:00Z | 2.0 | +| 2020-01-01T00:04:00Z | 3.0 | +{{% /flex-content %}} +{{% flex-content %}} +**`exact_mean` returns:** + +| _value | +|:------:| +| 1.5 | +{{% /flex-content %}} +{{< /flex >}} + +### exact_selector +A selector method that returns the data point for which at least `q` points are less than. +Output tables consist of a single row containing the calculated quantile. + +If calculating the `0.5` quantile or 50th percentile: + +{{< flex >}} +{{% flex-content %}} +**Given the following input table:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:01:00Z | 1.0 | +| 2020-01-01T00:02:00Z | 1.0 | +| 2020-01-01T00:03:00Z | 2.0 | +| 2020-01-01T00:04:00Z | 3.0 | +{{% /flex-content %}} +{{% flex-content %}} +**`exact_selector` returns:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:02:00Z | 1.0 | +{{% /flex-content %}} +{{< /flex >}} + +{{% note %}} +The examples below use the [example data variable](/influxdb/v2.1/query-data/flux/#example-data-variable). +{{% /note %}} + +## Find the value representing the 99th percentile +Use the default method, `"estimate_tdigest"`, to return all rows in a table that +contain values in the 99th percentile of data in the table. + +```js +data + |> quantile(q: 0.99) +``` + +## Find the average of values closest to the quantile +Use the `exact_mean` method to return a single row per input table containing the +average of the two values closest to the mathematical quantile of data in the table. +For example, to calculate the `0.99` quantile: + +```js +data + |> quantile(q: 0.99, method: "exact_mean") +``` + +## Find the point with the quantile value +Use the `exact_selector` method to return a single row per input table containing the +value that `q * 100`% of values in the table are less than. +For example, to calculate the `0.99` quantile: + +```js +data + |> quantile(q: 0.99, method: "exact_selector") +``` + +## Use quantile() with aggregateWindow() +[`aggregateWindow()`](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow/) +segments data into windows of time, aggregates data in each window into a single +point, and then removes the time-based segmentation. +It is primarily used to [downsample data](/influxdb/v2.1/process-data/common-tasks/downsample-data/). + +To specify the [quantile calculation method](#select-a-method-for-calculating-the-quantile) in +`aggregateWindow()`, use the [full function syntax](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow/#specify-parameters-of-the-aggregate-function): + +```js +data + |> aggregateWindow( + every: 5m, + fn: (tables=<-, column) => + tables + |> quantile(q: 0.99, method: "exact_selector") + ) +``` diff --git a/content/influxdb/v2.1/query-data/flux/query-fields.md b/content/influxdb/v2.1/query-data/flux/query-fields.md new file mode 100644 index 0000000000..b68e8c5d48 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/query-fields.md @@ -0,0 +1,82 @@ +--- +title: Query fields and tags +seotitle: Query fields and tags in InfluxDB using Flux +description: > + Use `filter()` to query data based on fields, tags, or any other column value. + `filter()` performs operations similar to the `SELECT` statement and the `WHERE` + clause in InfluxQL and other SQL-like query languages. +weight: 201 +menu: + influxdb_2_1: + parent: Query with Flux +influxdb/v2.1/tags: [query, select, where] +related: + - /{{< latest "flux" >}}/stdlib/universe/filter/ + - /influxdb/v2.1/query-data/flux/conditional-logic/ + - /influxdb/v2.1/query-data/flux/regular-expressions/ +list_code_example: | + ```js + from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "example-measurement" and + r._field == "example-field" and + r.tag == "example-tag" + ) + ``` +--- + +Use [`filter()`](/{{< latest "flux" >}}/stdlib/universe/filter/) +to query data based on fields, tags, or any other column value. +`filter()` performs operations similar to the `SELECT` statement and the `WHERE` +clause in InfluxQL and other SQL-like query languages. + +## The filter() function +`filter()` has an `fn` parameter that expects a [predicate function](/influxdb/v2.1/reference/glossary/#predicate-function), +an anonymous function comprised of one or more [predicate expressions](/influxdb/v2.1/reference/glossary/#predicate-expression). +The predicate function evaluates each input row. +Rows that evaluate to `true` are **included** in the output data. +Rows that evaluate to `false` are **excluded** from the output data. + +```js +// ... + |> filter(fn: (r) => r._measurement == "example-measurement" ) +``` + +The `fn` predicate function requires an `r` argument, which represents each row +as `filter()` iterates over input data. +Key-value pairs in the row record represent columns and their values. +Use [dot notation or bracket notation](/{{< latest "flux" >}}/data-types/composite/record/#reference-values-in-a-record) +to reference specific column values in the predicate function. +Use [logical operators](/{{< latest "flux" >}}/spec/operators/#logical-operators) +to chain multiple predicate expressions together. + +```js +// Row record +r = {foo: "bar", baz: "quz"} + +// Example predicate function +(r) => r.foo == "bar" and r["baz"] == "quz" + +// Evaluation results +(r) => true and true +``` + +## Filter by fields and tags +The combination of [`from()`](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/from), +[`range()`](/{{< latest "flux" >}}/stdlib/universe/range), +and `filter()` represent the most basic Flux query: + +1. Use `from()` to define your [bucket](/influxdb/v2.1/reference/glossary/#bucket). +2. Use `range()` to limit query results by time. +3. Use `filter()` to identify what rows of data to output. + +```js +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "example-measurement" and + r._field == "example-field" and + r.tag == "example-tag" + ) +``` diff --git a/content/influxdb/v2.1/query-data/flux/rate.md b/content/influxdb/v2.1/query-data/flux/rate.md new file mode 100644 index 0000000000..d930c6a36f --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/rate.md @@ -0,0 +1,176 @@ +--- +title: Calculate the rate of change +seotitle: Calculate the rate of change in Flux +list_title: Rate +description: > + Use `derivative()` to calculate the rate of change between subsequent values or + `aggregate.rate()` to calculate the average rate of change per window of time. + If time between points varies, these functions normalize points to a common time interval + making values easily comparable. +weight: 210 +menu: + influxdb_2_1: + parent: Query with Flux + name: Rate +influxdb/v2.1/tags: [query, rate] +related: + - /{{< latest "flux" >}}/stdlib/universe/derivative/ + - /{{< latest "flux" >}}/stdlib/experimental/aggregate/rate/ +list_query_example: rate_of_change +--- + + +Use [`derivative()`](/{{< latest "flux" >}}/stdlib/universe/derivative/) +to calculate the rate of change between subsequent values or +[`aggregate.rate()`](/{{< latest "flux" >}}/stdlib/experimental/to/aggregate/rate/) +to calculate the average rate of change per window of time. +If time between points varies, these functions normalize points to a common time interval +making values easily comparable. + +- [Rate of change between subsequent values](#rate-of-change-between-subsequent-values) +- [Average rate of change per window of time](#average-rate-of-change-per-window-of-time) + +## Rate of change between subsequent values +Use the [`derivative()` function](/{{< latest "flux" >}}/stdlib/universe/derivative/) +to calculate the rate of change per unit of time between subsequent _non-null_ values. + +```js +data + |> derivative(unit: 1s) +``` + +By default, `derivative()` returns only positive derivative values and replaces negative values with _null_. +Calculated values are returned as [floats](/{{< latest "flux" >}}/spec/types/#numeric-types). + +{{< flex >}} +{{% flex-content %}} +**Given the following input:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:00:00Z | 250 | +| 2020-01-01T00:04:00Z | 160 | +| 2020-01-01T00:12:00Z | 150 | +| 2020-01-01T00:19:00Z | 220 | +| 2020-01-01T00:32:00Z | 200 | +| 2020-01-01T00:51:00Z | 290 | +| 2020-01-01T01:00:00Z | 340 | +{{% /flex-content %}} +{{% flex-content %}} +**`derivative(unit: 1m)` returns:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:04:00Z | | +| 2020-01-01T00:12:00Z | | +| 2020-01-01T00:19:00Z | 10.0 | +| 2020-01-01T00:32:00Z | | +| 2020-01-01T00:51:00Z | 4.74 | +| 2020-01-01T01:00:00Z | 5.56 | +{{% /flex-content %}} +{{< /flex >}} + +Results represent the rate of change **per minute** between subsequent values with +negative values set to _null_. + +### Return negative derivative values +To return negative derivative values, set the `nonNegative` parameter to `false`, + +{{< flex >}} +{{% flex-content %}} +**Given the following input:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:00:00Z | 250 | +| 2020-01-01T00:04:00Z | 160 | +| 2020-01-01T00:12:00Z | 150 | +| 2020-01-01T00:19:00Z | 220 | +| 2020-01-01T00:32:00Z | 200 | +| 2020-01-01T00:51:00Z | 290 | +| 2020-01-01T01:00:00Z | 340 | +{{% /flex-content %}} +{{% flex-content %}} +**The following returns:** + +```js +|> derivative( + unit: 1m, + nonNegative: false +) +``` + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:04:00Z | -22.5 | +| 2020-01-01T00:12:00Z | -1.25 | +| 2020-01-01T00:19:00Z | 10.0 | +| 2020-01-01T00:32:00Z | -1.54 | +| 2020-01-01T00:51:00Z | 4.74 | +| 2020-01-01T01:00:00Z | 5.56 | +{{% /flex-content %}} +{{< /flex >}} + +Results represent the rate of change **per minute** between subsequent values and +include negative values. + +## Average rate of change per window of time + +Use the [`aggregate.rate()` function](/{{< latest "flux" >}}/stdlib/experimental/to/aggregate/rate/) +to calculate the average rate of change per window of time. + +```js +import "experimental/aggregate" + +data + |> aggregate.rate( + every: 1m, + unit: 1s, + groupColumns: ["tag1", "tag2"] + ) +``` + +`aggregate.rate()` returns the average rate of change (as a [float](/{{< latest "flux" >}}/spec/types/#numeric-types)) +per `unit` for time intervals defined by `every`. +Negative values are replaced with _null_. + +{{% note %}} +`aggregate.rate()` does not support `nonNegative: false`. +{{% /note %}} + +{{< flex >}} +{{% flex-content %}} +**Given the following input:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:00:00Z | 250 | +| 2020-01-01T00:04:00Z | 160 | +| 2020-01-01T00:12:00Z | 150 | +| 2020-01-01T00:19:00Z | 220 | +| 2020-01-01T00:32:00Z | 200 | +| 2020-01-01T00:51:00Z | 290 | +| 2020-01-01T01:00:00Z | 340 | +{{% /flex-content %}} +{{% flex-content %}} +**The following returns:** + +```js +|> aggregate.rate( + every: 20m, + unit: 1m +) +``` + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:20:00Z | 10.00 | +| 2020-01-01T00:40:00Z | | +| 2020-01-01T01:00:00Z | 4.74 | +| 2020-01-01T01:20:00Z | 5.56 | +{{% /flex-content %}} +{{< /flex >}} + +Results represent the **average change rate per minute** of every **20 minute interval** +with negative values set to _null_. +Timestamps represent the right bound of the time window used to average values. diff --git a/content/influxdb/v2.1/query-data/flux/regular-expressions.md b/content/influxdb/v2.1/query-data/flux/regular-expressions.md new file mode 100644 index 0000000000..b502872185 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/regular-expressions.md @@ -0,0 +1,97 @@ +--- +title: Use regular expressions in Flux +list_title: Regular expressions +description: This guide walks through using regular expressions in evaluation logic in Flux functions. +influxdb/v2.1/tags: [regex] +menu: + influxdb_2_1: + name: Regular expressions + parent: Query with Flux +weight: 220 +aliases: + - /influxdb/v2.1/query-data/guides/regular-expressions/ +related: + - /influxdb/v2.1/query-data/flux/query-fields/ + - /{{< latest "flux" >}}/stdlib/regexp/ +list_query_example: regular_expressions +--- + +Regular expressions (regexes) are incredibly powerful when matching patterns in large collections of data. +With Flux, regular expressions are primarily used for evaluation logic in predicate functions for things +such as filtering rows, dropping and keeping columns, state detection, etc. +This guide shows how to use regular expressions in your Flux scripts. + +If you're just getting started with Flux queries, check out the following: + +- [Get started with Flux](/{{< latest "flux" >}}/get-started/) for a conceptual overview of Flux and parts of a Flux query. +- [Execute queries](/influxdb/v2.1/query-data/execute-queries/) to discover a variety of ways to run your queries. + +## Go regular expression syntax +Flux uses Go's [regexp package](https://golang.org/pkg/regexp/) for regular expression search. +The links [below](#helpful-links) provide information about Go's regular expression syntax. + +## Regular expression operators +Flux provides two comparison operators for use with regular expressions. + +#### `=~` +When the expression on the left **MATCHES** the regular expression on the right, this evaluates to `true`. + +#### `!~` +When the expression on the left **DOES NOT MATCH** the regular expression on the right, this evaluates to `true`. + +## Regular expressions in Flux +When using regex matching in your Flux scripts, enclose your regular expressions with `/`. +The following is the basic regex comparison syntax: + +###### Basic regex comparison syntax +```js +expression =~ /regex/ +expression !~ /regex/ +``` +## Examples + +### Use a regex to filter by tag value +The following example filters records by the `cpu` tag. +It only keeps records for which the `cpu` is either `cpu0`, `cpu1`, or `cpu2`. + +```js +from(bucket: "example-bucket") + |> range(start: -15m) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_user" and + r.cpu =~ /cpu[0-2]$/ + ) +``` + +### Use a regex to filter by field key +The following example excludes records that do not have `_percent` in a field key. + +```js +from(bucket: "example-bucket") + |> range(start: -15m) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field =~ /_percent/ + ) +``` + +### Drop columns matching a regex +The following example drops columns whose names do not being with `_`. + +```js +from(bucket: "example-bucket") + |> range(start: -15m) + |> filter(fn: (r) => r._measurement == "mem") + |> drop(fn: (column) => column !~ /_.*/) +``` + +## Helpful links + +##### Syntax documentation +[regexp Syntax GoDoc](https://godoc.org/regexp/syntax) +[RE2 Syntax Overview](https://github.com/google/re2/wiki/Syntax) + +##### Go regex testers +[Regex Tester - Golang](https://regex-golang.appspot.com/assets/html/index.html) +[Regex101](https://regex101.com/) diff --git a/content/influxdb/v2.1/query-data/flux/scalar-values.md b/content/influxdb/v2.1/query-data/flux/scalar-values.md new file mode 100644 index 0000000000..fbd785656a --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/scalar-values.md @@ -0,0 +1,236 @@ +--- +title: Extract scalar values in Flux +list_title: Extract scalar values +description: > + Use Flux dynamic query functions to extract scalar values from Flux query output. + This lets you, for example, dynamically set variables using query results. +menu: + influxdb_2_1: + name: Extract scalar values + parent: Query with Flux +weight: 220 +influxdb/v2.1/tags: [scalar] +related: + - /{{< latest "flux" >}}/function-types/#dynamic-queries, Flux dynamic query functions +aliases: + - /influxdb/v2.1/query-data/guides/scalar-values/ +list_code_example: | + ```js + scalarValue = { + _record = + data + |> findRecord(fn: key => true, idx: 0) + return _record._value + } + ``` +--- + +Use Flux [dynamic query functions](/{{< latest "flux" >}}/function-types/#dynamic-queries) +to extract scalar values from Flux query output. +This lets you, for example, dynamically set variables using query results. + +**To extract scalar values from output:** + +1. [Extract a column from the input stream](#extract-a-column) + _**or**_ [extract a row from the input stream](#extract-a-row). +2. Use the returned array or record to reference scalar values. + +_The samples on this page use the [sample data provided below](#sample-data)._ + +{{% warn %}} +#### Current limitations +- The InfluxDB user interface (UI) does not currently support raw scalar output. + Use [`map()`](/{{< latest "flux" >}}/stdlib/universe/map/) to add + scalar values to output data. +{{% /warn %}} + +## Table extraction +Flux formats query results as a stream of tables. +Both [`findColumn()`](/{{< latest "flux" >}}/stdlib/universe/findcolumn/) +and [`findRecord()`](/{{< latest "flux" >}}/stdlib/universe/findrecord/) +extract the first table in a stream of tables whose [group key](/{{< latest "flux" >}}/get-started/data-model/#group-key) +values match the `fn` [predicate function](/{{< latest "flux" >}}/get-started/syntax-basics/#predicate-functions). + +{{% note %}} +#### Extract the correct table +Flux functions do not guarantee table order. +`findColumn()` and `findRecord` extract only the **first** table that matches the `fn` predicate. +To extract the correct table, be very specific in your predicate function or +filter and transform your data to minimize the number of tables piped-forward into the functions. +{{% /note %}} + +## Extract a column +Use the [`findColumn()` function](/{{< latest "flux" >}}/stdlib/universe/findcolumn/) +to output an array of values from a specific column in the extracted table. + +_See [Sample data](#sample-data) below._ + +```js +sampleData + |> findColumn( + fn: (key) => key._field == "temp" and key.location == "sfo", + column: "_value" + ) + +// Returns [65.1, 66.2, 66.3, 66.8] +``` + +### Use extracted column values +Use a variable to store the array of values. +In the example below, `SFOTemps` represents the array of values. +Reference a specific index (integer starting from `0`) in the array to return the +value at that index. + +_See [Sample data](#sample-data) below._ + +```js +SFOTemps = sampleData + |> findColumn( + fn: (key) => key._field == "temp" and key.location == "sfo", + column: "_value" + ) + +SFOTemps +// Returns [65.1, 66.2, 66.3, 66.8] + +SFOTemps[0] +// Returns 65.1 + +SFOTemps[2] +// Returns 66.3 +``` + +## Extract a row +Use the [`findRecord()` function](/{{< latest "flux" >}}/stdlib/universe/findrecord/) +to output data from a single row in the extracted table. +Specify the index of the row to output using the `idx` parameter. +The function outputs a record with key-value pairs for each column. + +```js +sampleData + |> findRecord( + fn: (key) => key._field == "temp" and key.location == "sfo", + idx: 0 + ) + +// Returns { +// _time:2019-11-11T12:00:00Z, +// _field:"temp", +// location:"sfo", +// _value: 65.1 +// } +``` + +### Use an extracted row record +Use a variable to store the extracted row record. +In the example below, `tempInfo` represents the extracted row. +Use [dot or bracket notation](/{{< latest "flux" >}}/data-types/composite/record/#dot-notation) +to reference keys in the record. + +```js +tempInfo = sampleData + |> findRecord( + fn: (key) => key._field == "temp" and key.location == "sfo", + idx: 0 + ) + +tempInfo +// Returns { +// _time:2019-11-11T12:00:00Z, +// _field:"temp", +// location:"sfo", +// _value: 65.1 +// } + +tempInfo._time +// Returns 2019-11-11T12:00:00Z + +tempInfo.location +// Returns sfo +``` + +## Example helper functions +Create custom helper functions to extract scalar values from query output. + +##### Extract a scalar field value +```js +// Define a helper function to extract field values +getFieldValue = (tables=<-, field) => { + extract = tables + |> findColumn( + fn: (key) => key._field == field, + column: "_value" + ) + return extract[0] +} + +// Use the helper function to define a variable +lastJFKTemp = sampleData + |> filter(fn: (r) => r.location == "kjfk") + |> last() + |> getFieldValue(field: "temp") + +lastJFKTemp +// Returns 71.2 +``` + +##### Extract scalar row data +```js +// Define a helper function to extract a row as a record +getRow = (tables=<-, field, idx=0) => { + extract = tables + |> findRecord( + fn: (key) => true, + idx: idx + ) + return extract +} + +// Use the helper function to define a variable +lastReported = sampleData + |> last() + |> getRow(idx: 0) + +"The last location to report was ${lastReported.location}. +The temperature was ${string(v: lastReported._value)}°F." + +// Returns: +// The last location to report was kord. +// The temperature was 38.9°F. +``` + +--- + +## Sample data + +The following sample data set represents fictional temperature metrics collected +from three locations. +It's formatted in [annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv/) and imported +into the Flux query using the [`csv.from()` function](/{{< latest "flux" >}}/stdlib/csv/from/). + +Place the following at the beginning of your query to use the sample data: + +{{% truncate %}} +```js +import "csv" + +sampleData = csv.from(csv: " +#datatype,string,long,dateTime:RFC3339,string,string,double +#group,false,true,false,true,true,false +#default,,,,,, +,result,table,_time,location,_field,_value +,,0,2019-11-01T12:00:00Z,sfo,temp,65.1 +,,0,2019-11-01T13:00:00Z,sfo,temp,66.2 +,,0,2019-11-01T14:00:00Z,sfo,temp,66.3 +,,0,2019-11-01T15:00:00Z,sfo,temp,66.8 +,,1,2019-11-01T12:00:00Z,kjfk,temp,69.4 +,,1,2019-11-01T13:00:00Z,kjfk,temp,69.9 +,,1,2019-11-01T14:00:00Z,kjfk,temp,71.0 +,,1,2019-11-01T15:00:00Z,kjfk,temp,71.2 +,,2,2019-11-01T12:00:00Z,kord,temp,46.4 +,,2,2019-11-01T13:00:00Z,kord,temp,46.3 +,,2,2019-11-01T14:00:00Z,kord,temp,42.7 +,,2,2019-11-01T15:00:00Z,kord,temp,38.9 +") +``` +{{% /truncate %}} diff --git a/content/influxdb/v2.1/query-data/flux/sort-limit.md b/content/influxdb/v2.1/query-data/flux/sort-limit.md new file mode 100644 index 0000000000..a03789ef00 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/sort-limit.md @@ -0,0 +1,74 @@ +--- +title: Sort and limit data with Flux +seotitle: Sort and limit data in InfluxDB with Flux +list_title: Sort and limit +description: > + Use `sort()` to order records within each table by specific columns and + `limit()` to limit the number of records in output tables to a fixed number, `n`. +influxdb/v2.1/tags: [sort, limit] +menu: + influxdb_2_1: + name: Sort and limit + parent: Query with Flux +weight: 203 +aliases: + - /influxdb/v2.1/query-data/guides/sort-limit/ +related: + - /{{< latest "flux" >}}/stdlib/universe/sort + - /{{< latest "flux" >}}/stdlib/universe/limit +list_query_example: sort_limit +--- + +Use [`sort()`](/{{< latest "flux" >}}/stdlib/universe/sort) +to order records within each table by specific columns and +[`limit()`](/{{< latest "flux" >}}/stdlib/universe/limit) +to limit the number of records in output tables to a fixed number, `n`. + +If you're just getting started with Flux queries, check out the following: + +- [Get started with Flux](/{{< latest "flux" >}}/get-started/) for a conceptual overview of Flux and parts of a Flux query. +- [Execute queries](/influxdb/v2.1/query-data/execute-queries/) to discover a variety of ways to run your queries. + +##### Example sorting system uptime + +The following example orders system uptime first by region, then host, then value. + +```js +from(bucket:"example-bucket") + |> range(start:-12h) + |> filter(fn: (r) => + r._measurement == "system" and + r._field == "uptime" + ) + |> sort(columns:["region", "host", "_value"]) +``` + +The [`limit()` function](/{{< latest "flux" >}}/stdlib/universe/limit) +limits the number of records in output tables to a fixed number, `n`. +The following example shows up to 10 records from the past hour. + +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> limit(n:10) +``` + +You can use `sort()` and `limit()` together to show the top N records. +The example below returns the 10 top system uptime values sorted first by +region, then host, then value. + +```js +from(bucket:"example-bucket") + |> range(start:-12h) + |> filter(fn: (r) => + r._measurement == "system" and + r._field == "uptime" + ) + |> sort(columns:["region", "host", "_value"]) + |> limit(n:10) +``` + +You now have created a Flux query that sorts and limits data. +Flux also provides the [`top()`](/{{< latest "flux" >}}/stdlib/universe/top) +and [`bottom()`](/{{< latest "flux" >}}/stdlib/universe/bottom) +functions to perform both of these functions at the same time. diff --git a/content/influxdb/v2.1/query-data/flux/sql.md b/content/influxdb/v2.1/query-data/flux/sql.md new file mode 100644 index 0000000000..540481c084 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/sql.md @@ -0,0 +1,384 @@ +--- +title: Query SQL data sources +seotitle: Query SQL data sources with InfluxDB +list_title: Query SQL data +description: > + The Flux `sql` package provides functions for working with SQL data sources. + Use `sql.from()` to query SQL databases like PostgreSQL, MySQL, Snowflake, + SQLite, Microsoft SQL Server, Amazon Athena, and Google BigQuery. +influxdb/v2.1/tags: [query, flux, sql] +menu: + influxdb_2_1: + parent: Query with Flux + list_title: SQL data +weight: 220 +aliases: + - /influxdb/v2.1/query-data/guides/sql/ +related: + - /{{< latest "flux" >}}/stdlib/sql/ +list_code_example: | + ```js + import "sql" + + sql.from( + driverName: "postgres", + dataSourceName: "postgresql://user:password@localhost", + query: "SELECT * FROM example_table" + ) + ``` +--- + +The [Flux](/influxdb/v2.1/reference/flux) `sql` package provides functions for working with SQL data sources. +[`sql.from()`](/{{< latest "flux" >}}/stdlib/sql/from/) lets you query SQL data sources +like [PostgreSQL](https://www.postgresql.org/), [MySQL](https://www.mysql.com/), +[Snowflake](https://www.snowflake.com/), [SQLite](https://www.sqlite.org/index.html), +[Microsoft SQL Server](https://www.microsoft.com/en-us/sql-server/default.aspx), +[Amazon Athena](https://aws.amazon.com/athena/) and [Google BigQuery](https://cloud.google.com/bigquery) +and use the results with InfluxDB dashboards, tasks, and other operations. + +- [Query a SQL data source](#query-a-sql-data-source) +- [Join SQL data with data in InfluxDB](#join-sql-data-with-data-in-influxdb) +- [Use SQL results to populate dashboard variables](#use-sql-results-to-populate-dashboard-variables) +- [Use secrets to store SQL database credentials](#use-secrets-to-store-sql-database-credentials) +- [Sample sensor data](#sample-sensor-data) + +If you're just getting started with Flux queries, check out the following: + +- [Get started with Flux](/{{< latest "flux" >}}/get-started/) for a conceptual overview of Flux and parts of a Flux query. +- [Execute queries](/influxdb/v2.1/query-data/execute-queries/) to discover a variety of ways to run your queries. + +## Query a SQL data source +To query a SQL data source: + +1. Import the `sql` package in your Flux query +2. Use the `sql.from()` function to specify the driver, data source name (DSN), + and query used to query data from your SQL data source: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[PostgreSQL](#) +[MySQL](#) +[Snowflake](#) +[SQLite](#) +[SQL Server](#) +[Athena](#) +[BigQuery](#) +{{% /code-tabs %}} + +{{% code-tab-content %}} +```js +import "sql" + +sql.from( + driverName: "postgres", + dataSourceName: "postgresql://user:password@localhost", + query: "SELECT * FROM example_table" +) +``` +{{% /code-tab-content %}} + +{{% code-tab-content %}} +```js +import "sql" + +sql.from( + driverName: "mysql", + dataSourceName: "user:password@tcp(localhost:3306)/db", + query: "SELECT * FROM example_table" +) +``` +{{% /code-tab-content %}} + +{{% code-tab-content %}} +```js +import "sql" + +sql.from( + driverName: "snowflake", + dataSourceName: "user:password@account/db/exampleschema?warehouse=wh", + query: "SELECT * FROM example_table" +) +``` +{{% /code-tab-content %}} + +{{% code-tab-content %}} +```js +// NOTE: InfluxDB OSS and InfluxDB Cloud do not have access to +// the local filesystem and cannot query SQLite data sources. +// Use the Flux REPL to query an SQLite data source. + +import "sql" + +sql.from( + driverName: "sqlite3", + dataSourceName: "file:/path/to/test.db?cache=shared&mode=ro", + query: "SELECT * FROM example_table" +) +``` +{{% /code-tab-content %}} + +{{% code-tab-content %}} +```js +import "sql" + +sql.from( + driverName: "sqlserver", + dataSourceName: "sqlserver://user:password@localhost:1234?database=examplebdb", + query: "GO SELECT * FROM Example.Table" +) +``` + +_For information about authenticating with SQL Server using ADO-style parameters, +see [SQL Server ADO authentication](/{{< latest "flux" >}}/stdlib/sql/from/#sql-server-ado-authentication)._ +{{% /code-tab-content %}} + +{{% code-tab-content %}} +```js +import "sql" +sql.from( + driverName: "awsathena", + dataSourceName: "s3://myorgqueryresults/?accessID=12ab34cd56ef®ion=region-name&secretAccessKey=y0urSup3rs3crEtT0k3n", + query: "GO SELECT * FROM Example.Table" +) +``` + +_For information about parameters to include in the Athena DSN, +see [Athena connection string](/{{< latest "flux" >}}/stdlib/sql/from/#athena-connection-string)._ +{{% /code-tab-content %}} +{{% code-tab-content %}} +```js +import "sql" +sql.from( + driverName: "bigquery", + dataSourceName: "bigquery://projectid/?apiKey=mySuP3r5ecR3tAP1K3y", + query: "SELECT * FROM exampleTable" +) +``` + +_For information about authenticating with BigQuery, see +[BigQuery authentication parameters](/{{< latest "flux" >}}/stdlib/sql/from/#bigquery-authentication-parameters)._ +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +_See the [`sql.from()` documentation](/{{< latest "flux" >}}/stdlib/sql/from/) for +information about required function parameters._ + +## Join SQL data with data in InfluxDB +One of the primary benefits of querying SQL data sources from InfluxDB +is the ability to enrich query results with data stored outside of InfluxDB. + +Using the [air sensor sample data](#sample-sensor-data) below, the following query +joins air sensor metrics stored in InfluxDB with sensor information stored in PostgreSQL. +The joined data lets you query and filter results based on sensor information +that isn't stored in InfluxDB. + +```js +// Import the "sql" package +import "sql" + +// Query data from PostgreSQL +sensorInfo = sql.from( + driverName: "postgres", + dataSourceName: "postgresql://localhost?sslmode=disable", + query: "SELECT * FROM sensors" +) + +// Query data from InfluxDB +sensorMetrics = from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "airSensors") + +// Join InfluxDB query results with PostgreSQL query results +join(tables: {metric: sensorMetrics, info: sensorInfo}, on: ["sensor_id"]) +``` + +## Use SQL results to populate dashboard variables +Use `sql.from()` to [create dashboard variables](/influxdb/v2.1/visualize-data/variables/create-variable/) +from SQL query results. +The following example uses the [air sensor sample data](#sample-sensor-data) below to +create a variable that lets you select the location of a sensor. + +```js +import "sql" + +sql.from( + driverName: "postgres", + dataSourceName: "postgresql://localhost?sslmode=disable", + query: "SELECT * FROM sensors" + ) + |> rename(columns: {location: "_value"}) + |> keep(columns: ["_value"]) +``` + +Use the variable to manipulate queries in your dashboards. + +{{< img-hd src="/img/influxdb/2-0-sql-dashboard-variable.png" alt="Dashboard variable from SQL query results" />}} + +--- + +## Use secrets to store SQL database credentials +If your SQL database requires authentication, use [InfluxDB secrets](/influxdb/v2.1/security/secrets/) +to store and populate connection credentials. +By default, InfluxDB base64-encodes and stores secrets in its internal key-value store, BoltDB. +For added security, [store secrets in Vault](/influxdb/v2.1/security/secrets/use-vault/). + +### Store your database credentials as secrets +Use the [InfluxDB API](/influxdb/v2.1/reference/api/) or the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/secret/) +to store your database credentials as secrets. + +{{< tabs-wrapper >}} +{{% tabs %}} +[InfluxDB API](#) +[influx CLI](#) +{{% /tabs %}} +{{% tab-content %}} +```sh +curl --request PATCH http://localhost:8086/api/v2/orgs//secrets \ + --header 'Authorization: Token YOURAUTHTOKEN' \ + --header 'Content-type: application/json' \ + --data '{ + "POSTGRES_HOST": "http://example.com", + "POSTGRES_USER": "example-username", + "POSTGRES_PASS": "example-password" +}' +``` + +**To store secrets, you need:** + +- [your organization ID](/influxdb/v2.1/organizations/view-orgs/#view-your-organization-id) +- [your API token](/influxdb/v2.1/security/tokens/view-tokens/) +{{% /tab-content %}} +{{% tab-content %}} +```sh +# Syntax +influx secret update -k + +# Example +influx secret update -k POSTGRES_PASS +``` + +**When prompted, enter your secret value.** + +{{% warn %}} +You can provide the secret value with the `-v`, `--value` flag, but the **plain text +secret may appear in your shell history**. + +```sh +influx secret update -k -v +``` +{{% /warn %}} +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +### Use secrets in your query +Import the `influxdata/influxdb/secrets` package and use [string interpolation](/{{< latest "flux" >}}/spec/string-interpolation/) +to populate connection credentials with stored secrets in your Flux query. + +```js +import "sql" +import "influxdata/influxdb/secrets" + +POSTGRES_HOST = secrets.get(key: "POSTGRES_HOST") +POSTGRES_USER = secrets.get(key: "POSTGRES_USER") +POSTGRES_PASS = secrets.get(key: "POSTGRES_PASS") + +sql.from( + driverName: "postgres", + dataSourceName: "postgresql://${POSTGRES_USER}:${POSTGRES_PASS}@${POSTGRES_HOST}", + query: "SELECT * FROM sensors" +) +``` + +--- + +## Sample sensor data +The [air sensor sample data](#download-sample-air-sensor-data) and +[sample sensor information](#import-the-sample-sensor-information) simulate a +group of sensors that measure temperature, humidity, and carbon monoxide +in rooms throughout a building. +Each collected data point is stored in InfluxDB with a `sensor_id` tag that identifies +the specific sensor it came from. +Sample sensor information is stored in PostgreSQL. + +**Sample data includes:** + +- Simulated data collected from each sensor and stored in the `airSensors` measurement in **InfluxDB**: + - temperature + - humidity + - co + +- Information about each sensor stored in the `sensors` table in **PostgreSQL**: + - sensor_id + - location + - model_number + - last_inspected + +#### Download sample air sensor data + +1. [Create a bucket](/influxdb/v2.1/organizations/buckets/create-bucket/) to store the data. +2. [Create an InfluxDB task](/influxdb/v2.1/process-data/manage-tasks/create-task/) + and use the [`sample.data()` function](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/sample/data/) + to download sample air sensor data every 15 minutes. + Write the downloaded sample data to your new bucket: + + ```js + import "influxdata/influxdb/sample" + + option task = { + name: "Collect sample air sensor data", + every: 15m + } + + sample.data(set: "airSensor") + |> to( + org: "example-org", + bucket: "example-bucket" + ) + ``` + +3. [Query your target bucket](/influxdb/v2.1/query-data/execute-queries/) after + the first task run to ensure the sample data is writing successfully. + + ```js + from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._measurement == "airSensors") + ``` + +#### Import the sample sensor information +1. [Download and install PostgreSQL](https://www.postgresql.org/download/). +2. Download the sample sensor information CSV. + + Download sample sensor information + +3. Use a PostgreSQL client (`psql` or a GUI) to create the `sensors` table: + + ``` + CREATE TABLE sensors ( + sensor_id character varying(50), + location character varying(50), + model_number character varying(50), + last_inspected date + ); + ``` + +4. Import the downloaded CSV sample data. + _Update the `FROM` file path to the path of the downloaded CSV sample data._ + + ``` + COPY sensors(sensor_id,location,model_number,last_inspected) + FROM '/path/to/sample-sensor-info.csv' DELIMITER ',' CSV HEADER; + ``` + +5. Query the table to ensure the data was imported correctly: + + ``` + SELECT * FROM sensors; + ``` + +#### Import the sample data dashboard +Download and import the Air Sensors dashboard to visualize the generated data: + +View Air Sensors dashboard JSON + +_For information about importing a dashboard, see [Create a dashboard](/influxdb/v2.1/visualize-data/dashboards/create-dashboard)._ diff --git a/content/influxdb/v2.1/query-data/flux/window-aggregate.md b/content/influxdb/v2.1/query-data/flux/window-aggregate.md new file mode 100644 index 0000000000..a22aa682f7 --- /dev/null +++ b/content/influxdb/v2.1/query-data/flux/window-aggregate.md @@ -0,0 +1,360 @@ +--- +title: Window and aggregate data with Flux +seotitle: Window and aggregate data in InfluxDB with Flux +list_title: Window & aggregate +description: > + This guide walks through windowing and aggregating data with Flux and outlines + how it shapes your data in the process. +menu: + influxdb_2_1: + name: Window & aggregate + parent: Query with Flux +weight: 204 +influxdb/v2.1/tags: [flux, aggregates] +aliases: + - /influxdb/v2.1/query-data/guides/window-aggregate/ +related: + - /{{< latest "flux" >}}/stdlib/universe/aggregatewindow + - /{{< latest "flux" >}}/stdlib/universe/window + - /{{< latest "flux" >}}/function-types/#aggregates, Flux aggregate functions + - /{{< latest "flux" >}}/function-types/#selectors, Flux selector functions +list_query_example: aggregate_window +--- + +A common operation performed with time series data is grouping data into windows of time, +or "windowing" data, then aggregating windowed values into a new value. +This guide walks through windowing and aggregating data with Flux and demonstrates +how data is shaped in the process. + +If you're just getting started with Flux queries, check out the following: + +- [Get started with Flux](/{{< latest "flux" >}}/get-started/) for a conceptual overview of Flux and parts of a Flux query. +- [Execute queries](/influxdb/v2.1/query-data/execute-queries/) to discover a variety of ways to run your queries. + +{{% note %}} +The following example is an in-depth walk-through of the steps required to window and aggregate data. +The [`aggregateWindow()` function](#summing-up) performs these operations for you, but understanding +how data is shaped in the process helps to successfully create your desired output. +{{% /note %}} + +## Data set +For the purposes of this guide, define a variable that represents your base data set. +The following example queries the memory usage of the host machine. + +```js +dataSet = from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> drop(columns: ["host"]) +``` + +{{% note %}} +This example drops the `host` column from the returned data since the memory data +is only tracked for a single host and it simplifies the output tables. +Dropping the `host` column is optional and not recommended if monitoring memory +on multiple hosts. +{{% /note %}} + +`dataSet` can now be used to represent your base data, which will look similar to the following: + +{{% truncate %}} +``` +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:50:00.000000000Z 71.11611366271973 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:50:10.000000000Z 67.39630699157715 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:50:20.000000000Z 64.16666507720947 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:50:30.000000000Z 64.19951915740967 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:50:40.000000000Z 64.2122745513916 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:50:50.000000000Z 64.22209739685059 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:51:00.000000000Z 64.6336555480957 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:51:10.000000000Z 64.16516304016113 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:51:20.000000000Z 64.18349742889404 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:51:30.000000000Z 64.20474052429199 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:51:40.000000000Z 68.65062713623047 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:51:50.000000000Z 67.20139980316162 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:52:00.000000000Z 70.9143877029419 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:52:10.000000000Z 64.14549350738525 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:52:20.000000000Z 64.15379047393799 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:52:30.000000000Z 64.1592264175415 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:52:40.000000000Z 64.18190002441406 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:52:50.000000000Z 64.28837776184082 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:53:00.000000000Z 64.29731845855713 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:53:10.000000000Z 64.36963081359863 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:53:20.000000000Z 64.37397003173828 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:53:30.000000000Z 64.44413661956787 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:53:40.000000000Z 64.42906856536865 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:53:50.000000000Z 64.44573402404785 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:00.000000000Z 64.48912620544434 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:10.000000000Z 64.49522972106934 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:20.000000000Z 64.48652744293213 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:30.000000000Z 64.49949741363525 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:40.000000000Z 64.4949197769165 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:50.000000000Z 64.49787616729736 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:55:00.000000000Z 64.49816226959229 +``` +{{% /truncate %}} + +## Windowing data +Use the [`window()` function](/{{< latest "flux" >}}/stdlib/universe/window) +to group your data based on time bounds. +The most common parameter passed with the `window()` is `every` which +defines the duration of time between windows. +Other parameters are available, but for this example, window the base data +set into one minute windows. + +```js +dataSet + |> window(every: 1m) +``` + +{{% note %}} +The `every` parameter supports all [valid duration units](/{{< latest "flux" >}}/spec/types/#duration-types), +including **calendar months (`1mo`)** and **years (`1y`)**. +{{% /note %}} + +Each window of time is output in its own table containing all records that fall within the window. + +{{% truncate %}} +###### window() output tables +``` +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-03T17:50:00.000000000Z 2018-11-03T17:51:00.000000000Z used_percent mem 2018-11-03T17:50:00.000000000Z 71.11611366271973 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:51:00.000000000Z used_percent mem 2018-11-03T17:50:10.000000000Z 67.39630699157715 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:51:00.000000000Z used_percent mem 2018-11-03T17:50:20.000000000Z 64.16666507720947 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:51:00.000000000Z used_percent mem 2018-11-03T17:50:30.000000000Z 64.19951915740967 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:51:00.000000000Z used_percent mem 2018-11-03T17:50:40.000000000Z 64.2122745513916 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:51:00.000000000Z used_percent mem 2018-11-03T17:50:50.000000000Z 64.22209739685059 + + +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-03T17:51:00.000000000Z 2018-11-03T17:52:00.000000000Z used_percent mem 2018-11-03T17:51:00.000000000Z 64.6336555480957 +2018-11-03T17:51:00.000000000Z 2018-11-03T17:52:00.000000000Z used_percent mem 2018-11-03T17:51:10.000000000Z 64.16516304016113 +2018-11-03T17:51:00.000000000Z 2018-11-03T17:52:00.000000000Z used_percent mem 2018-11-03T17:51:20.000000000Z 64.18349742889404 +2018-11-03T17:51:00.000000000Z 2018-11-03T17:52:00.000000000Z used_percent mem 2018-11-03T17:51:30.000000000Z 64.20474052429199 +2018-11-03T17:51:00.000000000Z 2018-11-03T17:52:00.000000000Z used_percent mem 2018-11-03T17:51:40.000000000Z 68.65062713623047 +2018-11-03T17:51:00.000000000Z 2018-11-03T17:52:00.000000000Z used_percent mem 2018-11-03T17:51:50.000000000Z 67.20139980316162 + + +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-03T17:52:00.000000000Z 2018-11-03T17:53:00.000000000Z used_percent mem 2018-11-03T17:52:00.000000000Z 70.9143877029419 +2018-11-03T17:52:00.000000000Z 2018-11-03T17:53:00.000000000Z used_percent mem 2018-11-03T17:52:10.000000000Z 64.14549350738525 +2018-11-03T17:52:00.000000000Z 2018-11-03T17:53:00.000000000Z used_percent mem 2018-11-03T17:52:20.000000000Z 64.15379047393799 +2018-11-03T17:52:00.000000000Z 2018-11-03T17:53:00.000000000Z used_percent mem 2018-11-03T17:52:30.000000000Z 64.1592264175415 +2018-11-03T17:52:00.000000000Z 2018-11-03T17:53:00.000000000Z used_percent mem 2018-11-03T17:52:40.000000000Z 64.18190002441406 +2018-11-03T17:52:00.000000000Z 2018-11-03T17:53:00.000000000Z used_percent mem 2018-11-03T17:52:50.000000000Z 64.28837776184082 + + +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-03T17:53:00.000000000Z 2018-11-03T17:54:00.000000000Z used_percent mem 2018-11-03T17:53:00.000000000Z 64.29731845855713 +2018-11-03T17:53:00.000000000Z 2018-11-03T17:54:00.000000000Z used_percent mem 2018-11-03T17:53:10.000000000Z 64.36963081359863 +2018-11-03T17:53:00.000000000Z 2018-11-03T17:54:00.000000000Z used_percent mem 2018-11-03T17:53:20.000000000Z 64.37397003173828 +2018-11-03T17:53:00.000000000Z 2018-11-03T17:54:00.000000000Z used_percent mem 2018-11-03T17:53:30.000000000Z 64.44413661956787 +2018-11-03T17:53:00.000000000Z 2018-11-03T17:54:00.000000000Z used_percent mem 2018-11-03T17:53:40.000000000Z 64.42906856536865 +2018-11-03T17:53:00.000000000Z 2018-11-03T17:54:00.000000000Z used_percent mem 2018-11-03T17:53:50.000000000Z 64.44573402404785 + + +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-03T17:54:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:00.000000000Z 64.48912620544434 +2018-11-03T17:54:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:10.000000000Z 64.49522972106934 +2018-11-03T17:54:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:20.000000000Z 64.48652744293213 +2018-11-03T17:54:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:30.000000000Z 64.49949741363525 +2018-11-03T17:54:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:40.000000000Z 64.4949197769165 +2018-11-03T17:54:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:50.000000000Z 64.49787616729736 + + +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-03T17:55:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:55:00.000000000Z 64.49816226959229 +``` +{{% /truncate %}} + +When visualized in the InfluxDB UI, each window table is displayed in a different color. + +![Windowed data](/img/flux/simple-windowed-data.png) + +## Aggregate data +[Aggregate functions](/{{< latest "flux" >}}/function-types#aggregates) take the values +of all rows in a table and use them to perform an aggregate operation. +The result is output as a new value in a single-row table. + +Since windowed data is split into separate tables, aggregate operations run against +each table separately and output new tables containing only the aggregated value. + +For this example, use the [`mean()` function](/{{< latest "flux" >}}/stdlib/universe/mean) +to output the average of each window: + +```js +dataSet + |> window(every: 1m) + |> mean() +``` + +{{% truncate %}} +###### mean() output tables +``` +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------------- +2018-11-03T17:50:00.000000000Z 2018-11-03T17:51:00.000000000Z used_percent mem 65.88549613952637 + + +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------------- +2018-11-03T17:51:00.000000000Z 2018-11-03T17:52:00.000000000Z used_percent mem 65.50651391347249 + + +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------------- +2018-11-03T17:52:00.000000000Z 2018-11-03T17:53:00.000000000Z used_percent mem 65.30719598134358 + + +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------------- +2018-11-03T17:53:00.000000000Z 2018-11-03T17:54:00.000000000Z used_percent mem 64.39330975214641 + + +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------------- +2018-11-03T17:54:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 64.49386278788249 + + +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ---------------------------- +2018-11-03T17:55:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 64.49816226959229 +``` +{{% /truncate %}} + +Because each data point is contained in its own table, when visualized, +they appear as single, unconnected points. + +![Aggregated windowed data](/img/flux/simple-windowed-aggregate-data.png) + +### Recreate the time column +**Notice the `_time` column is not in the [aggregated output tables](#mean-output-tables).** +Because records in each table are aggregated together, their timestamps no longer +apply and the column is removed from the group key and table. + +Also notice the `_start` and `_stop` columns still exist. +These represent the lower and upper bounds of the time window. + +Many Flux functions rely on the `_time` column. +To further process your data after an aggregate function, you need to re-add `_time`. +Use the [`duplicate()` function](/{{< latest "flux" >}}/stdlib/universe/duplicate) to +duplicate either the `_start` or `_stop` column as a new `_time` column. + +```js +dataSet + |> window(every: 1m) + |> mean() + |> duplicate(column: "_stop", as: "_time") +``` + +{{% truncate %}} +###### duplicate() output tables +``` +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-03T17:50:00.000000000Z 2018-11-03T17:51:00.000000000Z used_percent mem 2018-11-03T17:51:00.000000000Z 65.88549613952637 + + +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-03T17:51:00.000000000Z 2018-11-03T17:52:00.000000000Z used_percent mem 2018-11-03T17:52:00.000000000Z 65.50651391347249 + + +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-03T17:52:00.000000000Z 2018-11-03T17:53:00.000000000Z used_percent mem 2018-11-03T17:53:00.000000000Z 65.30719598134358 + + +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-03T17:53:00.000000000Z 2018-11-03T17:54:00.000000000Z used_percent mem 2018-11-03T17:54:00.000000000Z 64.39330975214641 + + +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-03T17:54:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:55:00.000000000Z 64.49386278788249 + + +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-03T17:55:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:55:00.000000000Z 64.49816226959229 +``` +{{% /truncate %}} + +## "Unwindow" aggregate tables +Keeping aggregate values in separate tables generally isn't the format in which you want your data. +Use the `window()` function to "unwindow" your data into a single infinite (`inf`) window. + +```js +dataSet + |> window(every: 1m) + |> mean() + |> duplicate(column: "_stop", as: "_time") + |> window(every: inf) +``` + +{{% note %}} +Windowing requires a `_time` column which is why it's necessary to +[recreate the `_time` column](#recreate-the-time-column) after an aggregation. +{{% /note %}} + +###### Unwindowed output table +``` +Table: keys: [_start, _stop, _field, _measurement] + _start:time _stop:time _field:string _measurement:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:51:00.000000000Z 65.88549613952637 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:52:00.000000000Z 65.50651391347249 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:53:00.000000000Z 65.30719598134358 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:54:00.000000000Z 64.39330975214641 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:55:00.000000000Z 64.49386278788249 +2018-11-03T17:50:00.000000000Z 2018-11-03T17:55:00.000000000Z used_percent mem 2018-11-03T17:55:00.000000000Z 64.49816226959229 +``` + +With the aggregate values in a single table, data points in the visualization are connected. + +![Unwindowed aggregate data](/img/flux/simple-unwindowed-data.png) + +## Summing up +You have now created a Flux query that windows and aggregates data. +The data transformation process outlined in this guide should be used for all aggregation operations. + +Flux also provides the [`aggregateWindow()` function](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow) +which performs all these separate functions for you. + +The following Flux query will return the same results: + +###### aggregateWindow function +```js +dataSet + |> aggregateWindow(every: 1m, fn: mean) +``` diff --git a/content/influxdb/v2.1/query-data/get-started/_index.md b/content/influxdb/v2.1/query-data/get-started/_index.md new file mode 100644 index 0000000000..843d574a60 --- /dev/null +++ b/content/influxdb/v2.1/query-data/get-started/_index.md @@ -0,0 +1,35 @@ +--- +title: Get started with Flux and InfluxDB +description: > + Get started with Flux, the functional data scripting language, and learn the + basics of writing a Flux query that queries InfluxDB. +aliases: + - /influxdb/v2.1/query-data/get-started/getting-started +weight: 101 +influxdb/v2.1/tags: [query, flux, get-started] +menu: + influxdb_2_1: + name: Get started with Flux + parent: Query data +related: + - /{{< latest "flux" >}}/get-started/ + - /{{< latest "flux" >}}/ + - /{{< latest "flux" >}}/stdlib/ +--- + +Flux is InfluxData's functional data scripting language designed for querying, +analyzing, and acting on data. + +These guides walks through important concepts related to Flux and querying time +series data from InfluxDB using Flux. + +## Tools for working with Flux +The [Execute queries](/influxdb/v2.1/query-data/execute-queries) guide walks through +the different tools available for querying InfluxDB with Flux. + +## Before you start +To get a basic understanding of the Flux data model and syntax, see +[Get started with Flux](/{{< latest "flux" >}}/get-started/) in the +[Flux documentation](/{{< latest "flux" >}}/). + +{{< page-nav next="/influxdb/v2.1/query-data/get-started/query-influxdb/" >}} diff --git a/content/influxdb/v2.1/query-data/get-started/query-influxdb.md b/content/influxdb/v2.1/query-data/get-started/query-influxdb.md new file mode 100644 index 0000000000..1b7d7c26a8 --- /dev/null +++ b/content/influxdb/v2.1/query-data/get-started/query-influxdb.md @@ -0,0 +1,141 @@ +--- +title: Query InfluxDB with Flux +description: Learn the basics of using Flux to query data from InfluxDB. +influxdb/v2.1/tags: [query, flux] +menu: + influxdb_2_1: + name: Query InfluxDB + parent: Get started with Flux +weight: 201 +related: + - /{{< latest "flux" >}}/get-started/query-basics/ + - /influxdb/v2.1/query-data/flux/ + - /{{< latest "flux" >}}/stdlib/influxdata/influxdb/from + - /{{< latest "flux" >}}/stdlib/universe/range + - /{{< latest "flux" >}}/stdlib/universe/filter +--- + +This guide walks through the basics of using Flux to query data from InfluxDB. +Every Flux query needs the following: + +1. [A data source](#1-define-your-data-source) +2. [A time range](#2-specify-a-time-range) +3. [Data filters](#3-filter-your-data) + + +## 1. Define your data source +Flux's [`from()`](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/from/) function defines an InfluxDB data source. +It requires a [`bucket`](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/from/#bucket) parameter. +The following examples use `example-bucket` as the bucket name. + +```js +from(bucket:"example-bucket") +``` + +## 2. Specify a time range +Flux requires a time range when querying time series data. +"Unbounded" queries are very resource-intensive and as a protective measure, +Flux will not query the database without a specified range. + +Use the [pipe-forward operator](/{{< latest "flux" >}}/get-started/syntax-basics/#pipe-forward-operator) +(`|>`) to pipe data from your data source into +[`range()`](/{{< latest "flux" >}}/stdlib/universe/range), which specifies a time range for your query. +It accepts two parameters: `start` and `stop`. +Start and stop values can be **relative** using negative [durations](/{{< latest "flux" >}}/data-types/basic/duration/) +or **absolute** using [timestamps](/{{< latest "flux" >}}/data-types/basic/time/). + +###### Example relative time ranges +```js +// Relative time range with start only. Stop defaults to now. +from(bucket:"example-bucket") + |> range(start: -1h) + +// Relative time range with start and stop +from(bucket:"example-bucket") + |> range(start: -1h, stop: -10m) +``` + +{{% note %}} +Relative ranges are relative to "now." +{{% /note %}} + +###### Example absolute time range +```js +from(bucket:"example-bucket") + |> range(start: 2021-01-01T00:00:00Z, stop: 2021-01-01T12:00:00Z) +``` + +#### Use the following: +For this guide, use the relative time range, `-15m`, to limit query results to data from the last 15 minutes: + +```js +from(bucket:"example-bucket") + |> range(start: -15m) +``` + +## 3. Filter your data +Pass your ranged data into `filter()` to narrow results based on data attributes or columns. +`filter()` has one parameter, `fn`, which expects a +[predicate function](/{{< latest "flux" >}}/get-started/syntax-basics/#predicate-functions) +evaluates rows by column values. + +`filter()` iterates over every input row and structures row data as a Flux +[record](/{{< latest "flux" >}}/data-types/composite/record/). +The record is passed into the predicate function as `r` where it is evaluated using +[predicate expressions](/{{< latest "flux" >}}/get-started/syntax-basics/#predicate-expressions). + +Rows that evaluate to `false` are dropped from the output data. +Rows that evaluate to `true` persist in the output data. + +```js +// Pattern +(r) => (r.recordProperty comparisonOperator comparisonExpression) + +// Example with single filter +(r) => (r._measurement == "cpu") + +// Example with multiple filters +(r) => r._measurement == "cpu" and r._field != "usage_system") +``` + +#### Use the following: +For this example, filter by the `cpu` measurement, `usage_system` field, and +`cpu-total` tag value: + +```js +from(bucket:"example-bucket") + |> range(start: -15m) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) +``` + +## 4. Yield your queried data +[`yield()`](/{{< latest "flux" >}}/stdlib/universe/yield/) outputs the result of the query. + +```js +from(bucket:"example-bucket") + |> range(start: -15m) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + |> yield() +``` + +Flux automatically assumes a `yield()` function at +the end of each script to output and visualize the data. +Explicitly calling `yield()` is only necessary when including multiple queries +in the same Flux query. +Each set of returned data needs to be named using the `yield()` function. + +## Congratulations! +You have now queried data from InfluxDB using Flux. + +The query shown here is a basic example. +Flux queries can be extended in many ways to form powerful scripts. + +{{< page-nav prev="/influxdb/v2.1/query-data/get-started/" next="/influxdb/v2.1/query-data/get-started/transform-data/" >}} diff --git a/content/influxdb/v2.1/query-data/get-started/transform-data.md b/content/influxdb/v2.1/query-data/get-started/transform-data.md new file mode 100644 index 0000000000..76ddfaadf9 --- /dev/null +++ b/content/influxdb/v2.1/query-data/get-started/transform-data.md @@ -0,0 +1,186 @@ +--- +title: Transform data with Flux +description: Learn the basics of using Flux to transform data queried from InfluxDB. +influxdb/v2.1/tags: [flux, transform, query] +menu: + influxdb_2_1: + name: Transform data + parent: Get started with Flux +weight: 202 +related: + - /{{< latest "flux" >}}/stdlib/universe/aggregatewindow + - /{{< latest "flux" >}}/stdlib/universe/window +--- + +When [querying data from InfluxDB](/influxdb/v2.1/query-data/get-started/query-influxdb), +you often need to transform that data in some way. +Common examples are aggregating data, downsampling data, etc. + +This guide demonstrates using [Flux functions](/{{< latest "flux" >}}/stdlib/) to transform your data. +It walks through creating a Flux script that partitions data into windows of time, +averages the `_value`s in each window, and outputs the averages as a new table. + +{{% note %}} +If you're not familiar with how Flux structures and operates on data, see +[Flux data model](/{{< latest "flux" >}}/get-started/data-model/). +{{% /note %}} + +## Query data +Use the query built in the previous [Query data from InfluxDB](/influxdb/v2.1/query-data/get-started/query-influxdb) +guide, but update the range to pull data from the last hour: + +```js +from(bucket:"example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) +``` + +## Flux functions +Flux provides a number of functions that perform specific operations, transformations, and tasks. +You can also [create custom functions](/influxdb/v2.1/query-data/flux/custom-functions) in your Flux queries. +_Functions are covered in detail in the [Flux standard library](/{{< latest "flux" >}}/stdlib/) documentation._ + +A common type of function used when transforming data queried from InfluxDB is an aggregate function. +Aggregate functions take a set of `_value`s in a table, aggregate them, and transform +them into a new value. + +This example uses the [`mean()` function](/{{< latest "flux" >}}/stdlib/universe/mean) +to average values within each time window. + +{{% note %}} +The following example walks through the steps required to window and aggregate data, +but there is a [`aggregateWindow()` helper function](#helper-functions) that does it for you. +It's just good to understand the steps in the process. +{{% /note %}} + +## Window your data +Flux's [`window()` function](/{{< latest "flux" >}}/stdlib/universe/window) partitions records based on a time value. +Use the `every` parameter to define a duration of each window. + +{{% note %}} +#### Calendar months and years +`every` supports all [valid duration units](/{{< latest "flux" >}}/spec/types/#duration-types), +including **calendar months (`1mo`)** and **years (`1y`)**. +{{% /note %}} + +For this example, window data in five minute intervals (`5m`). + +```js +from(bucket:"example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + |> window(every: 5m) +``` + +As data is gathered into windows of time, each window is output as its own table. +When visualized, each table is assigned a unique color. + +![Windowed data tables](/img/flux/windowed-data.png) + +## Aggregate windowed data +Flux aggregate functions take the `_value`s in each table and aggregate them in some way. +Use the [`mean()` function](/{{< latest "flux" >}}/stdlib/universe/mean) to average the `_value`s of each table. + +```js +from(bucket:"example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + |> window(every: 5m) + |> mean() +``` + +As rows in each window are aggregated, their output table contains only a single row with the aggregate value. +Windowed tables are all still separate and, when visualized, will appear as single, unconnected points. + +![Windowed aggregate data](/img/flux/windowed-aggregates.png) + +## Add times to your aggregates +As values are aggregated, the resulting tables do not have a `_time` column because +the records used for the aggregation all have different timestamps. +Aggregate functions don't infer what time should be used for the aggregate value. +Therefore the `_time` column is dropped. + +A `_time` column is required in the [next operation](#unwindow-aggregate-tables). +To add one, use the [`duplicate()` function](/{{< latest "flux" >}}/stdlib/universe/duplicate) +to duplicate the `_stop` column as the `_time` column for each windowed table. + +```js +from(bucket:"example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + |> window(every: 5m) + |> mean() + |> duplicate(column: "_stop", as: "_time") +``` + +## Unwindow aggregate tables + +Use the `window()` function with the `every: inf` parameter to gather all points +into a single, infinite window. + +```js +from(bucket:"example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + |> window(every: 5m) + |> mean() + |> duplicate(column: "_stop", as: "_time") + |> window(every: inf) +``` + +Once ungrouped and combined into a single table, the aggregate data points will appear connected in your visualization. + +![Unwindowed aggregate data](/img/flux/windowed-aggregates-ungrouped.png) + +## Helper functions +This may seem like a lot of coding just to build a query that aggregates data, however going through the +process helps to understand how data changes "shape" as it is passed through each function. + +Flux provides (and allows you to create) "helper" functions that abstract many of these steps. +The same operation performed in this guide can be accomplished using +[`aggregateWindow()`](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow). + +```js +from(bucket:"example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + |> aggregateWindow(every: 5m, fn: mean) +``` + +## Congratulations! +You have now constructed a Flux query that uses Flux functions to transform your data. +There are many more ways to manipulate your data using both Flux's primitive functions +and your own custom functions, but this is a good introduction into the basic syntax and query structure. + +--- + +_For a deeper dive into windowing and aggregating data with example data output for each transformation, +view the [Window and aggregate data](/influxdb/v2.1/query-data/flux/window-aggregate) guide._ + +--- + +{{< page-nav prev="/influxdb/v2.1/query-data/get-started/query-influxdb/" >}} diff --git a/content/influxdb/v2.1/query-data/influxql.md b/content/influxdb/v2.1/query-data/influxql.md new file mode 100644 index 0000000000..b0c37a0786 --- /dev/null +++ b/content/influxdb/v2.1/query-data/influxql.md @@ -0,0 +1,250 @@ +--- +title: Query data with InfluxQL +description: > + Use the [InfluxDB 1.x `/query` compatibility endpoint](/influxdb/v2.1/reference/api/influxdb-1x/query) + to query data in InfluxDB Cloud and InfluxDB OSS 2.1 with **InfluxQL**. +weight: 102 +influxdb/v2.1/tags: [influxql, query] +menu: + influxdb_2_1: + name: Query with InfluxQL + parent: Query data +related: + - /influxdb/v2.1/reference/api/influxdb-1x/ + - /influxdb/v2.1/reference/api/influxdb-1x/query + - /influxdb/v2.1/reference/api/influxdb-1x/dbrp +--- + +In InfluxDB 1.x, data is stored in [databases](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#database) +and [retention policies](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#retention-policy-rp). +In InfluxDB OSS {{< current-version >}}, data is stored in [buckets](/influxdb/v2.1/reference/glossary/#bucket). +Because InfluxQL uses the 1.x data model, a bucket must be mapped to a database and retention policy (DBRP) before it can be queried using InfluxQL. + +{{% note %}} +#### InfluxQL reference documentation +For complete InfluxQL reference documentation, see +[Influx Query Language in the latest InfluxDB 1.x documentation](/{{< latest "influxdb" "v1" >}}/query_language/). +{{% /note %}} + +**To use InfluxQL to query bucket data, complete the following steps:** + +1. [Verify buckets have a mapping](#verify-buckets-have-a-mapping). +2. [Map unmapped buckets](#map-unmapped-buckets). +3. [Query a mapped bucket with InfluxQL](#query-a-mapped-bucket-with-influxql). + +## Verify buckets have a mapping + +{{% note %}} +When [upgrading from InfluxDB 1.x to {{< current-version >}}](/influxdb/v2.1/upgrade/v1-to-v2/), +database and retention policy combinations are mapped to InfluxDB {{< current-version >}} buckets. +For more information, see [Database and retention policy mapping](/influxdb/v2.1/reference/api/influxdb-1x/dbrp/). +If you're not sure how data was written into a bucket, verify the bucket has a mapping. +{{% /note %}} + +Use the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) or the [InfluxDB API](/influxdb/v2.1/reference/api/) +to verify the buckets you want to query are mapped to a database and retention policy. + +{{< tabs-wrapper >}} +{{% tabs %}} +[influx CLI](#) +[InfluxDB API](#) +{{% /tabs %}} +{{% tab-content %}} + +Use the [`influx v1 dbrp list` command](/influxdb/v2.1/reference/cli/influx/v1/dbrp/list/) to list DBRP mappings. + +{{% note %}} +The examples below assume that your organization and API token are +provided by the active [InfluxDB connection configuration](/influxdb/v2.1/reference/cli/influx/config/) in the `influx` CLI. +If not, include your organization (`--org`) and API token (`--token`) with each command. +{{% /note %}} + +##### View all DBRP mappings +```sh +influx v1 dbrp list +``` + +##### Filter DBRP mappings by database +```sh +influx v1 dbrp list --db example-db +``` + +##### Filter DBRP mappings by bucket ID +```sh +influx v1 dbrp list --bucket-id 00oxo0oXx000x0Xo +``` +{{% /tab-content %}} +{{% tab-content %}} +Use the [`/api/v2/dbrps` API endpoint](/influxdb/v2.1/api/#operation/GetDBRPs) to list DBRP mappings. +Include the following: + +- **Request method:** `GET` +- **Headers:** + - **Authorization:** `Token` schema with your InfluxDB [API token](/influxdb/v2.1/security/tokens/) +- **Query parameters:** + {{< req type="key" >}} + - {{< req "\*" >}} **orgID:** [organization ID](/influxdb/v2.1/organizations/view-orgs/#view-your-organization-id) + - **bucketID:** [bucket ID](/influxdb/v2.1/organizations/buckets/view-buckets/) _(to list DBRP mappings for a specific bucket)_ + - **database:** database name _(to list DBRP mappings with a specific database name)_ + - **rp:** retention policy name _(to list DBRP mappings with a specific retention policy name)_ + - **id:** DBRP mapping ID _(to list a specific DBRP mapping)_ + +##### View all DBRP mappings +```sh +curl --request GET \ + http://localhost:8086/api/v2/dbrps?orgID=00oxo0oXx000x0Xo \ + --header "Authorization: Token YourAuthToken" +``` + +##### Filter DBRP mappings by database +```sh +curl --request GET \ + http://localhost:8086/api/v2/dbrps?orgID=00oxo0oXx000x0Xo&db=example-db \ + --header "Authorization: Token YourAuthToken" +``` + +##### Filter DBRP mappings by bucket ID +```sh +curl --request GET \ + https://cloud2.influxdata.com/api/v2/dbrps?organization_id=00oxo0oXx000x0Xo&bucketID=00oxo0oXx000x0Xo \ + --header "Authorization: Token YourAuthToken" +``` +{{% /tab-content %}} +{{% /tabs-wrapper %}} + +If you **do not find a DBRP mapping for a bucket**, complete the next procedure to map the unmapped bucket. +_For more information on the DBRP mapping API, see the [`/api/v2/dbrps` endpoint documentation](/influxdb/v2.1/api/#tag/DBRPs)._ + +## Map unmapped buckets +Use the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) or the [InfluxDB API](/influxdb/v2.1/reference/api/) +to manually create DBRP mappings for unmapped buckets. + +{{< tabs-wrapper >}} +{{% tabs %}} +[influx CLI](#) +[InfluxDB API](#) +{{% /tabs %}} +{{% tab-content %}} + +Use the [`influx v1 dbrp create` command](/influxdb/v2.1/reference/cli/influx/v1/dbrp/create/) +to map an unmapped bucket to a database and retention policy. +Include the following: + +{{< req type="key" >}} + +- {{< req "\*" >}} **org** and **token** to authenticate. We recommend setting your organization and token to your active InfluxDB connection configuration in the influx CLI, so you don't have to add these parameters to each command. To set up your active InfluxDB configuration, see [`influx config set`](/influxdb/v2.1/reference/cli/influx/config/set/). +- {{< req "\*" >}} **database name** to map +- {{< req "\*" >}} **retention policy** name to map +- {{< req "\*" >}} [Bucket ID](/influxdb/v2.1/organizations/buckets/view-buckets/#view-buckets-in-the-influxdb-ui) to map to +- **Default flag** to set the provided retention policy as the default retention policy for the database + +```sh +influx v1 dbrp create \ + --db example-db \ + --rp example-rp \ + --bucket-id 00oxo0oXx000x0Xo \ + --default +``` + +{{% /tab-content %}} +{{% tab-content %}} + +Use the [`/api/v2/dbrps` API endpoint](/influxdb/v2.1/api/#operation/PostDBRP) to create a new DBRP mapping. +Include the following: + +- **Request method:** `POST` +- **Headers:** + - **Authorization:** `Token` schema with your InfluxDB [API token](/influxdb/v2.1/security/tokens/) + - **Content-type:** `application/json` +- **Request body:** JSON object with the following fields: + {{< req type="key" >}} + - {{< req "\*" >}} **bucketID:** [bucket ID](/influxdb/v2.1/organizations/buckets/view-buckets/) + - {{< req "\*" >}} **database:** database name + - **default:** set the provided retention policy as the default retention policy for the database + - {{< req "\*" >}} **org** or **orgID:** organization name or [organization ID](/influxdb/v2.1/organizations/view-orgs/#view-your-organization-id) + - {{< req "\*" >}} **retention_policy:** retention policy name + + +```sh +curl --request POST http://localhost:8086/api/v2/dbrps \ + --header "Authorization: Token YourAuthToken" \ + --header 'Content-type: application/json' \ + --data '{ + "bucketID": "00oxo0oXx000x0Xo", + "database": "example-db", + "default": true, + "orgID": "00oxo0oXx000x0Xo", + "retention_policy": "example-rp" + }' +``` + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +After you've verified the bucket is mapped, query the bucket using the `query` 1.x compatibility endpoint. + +## Query a mapped bucket with InfluxQL + +The [InfluxDB 1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/) supports +all InfluxDB 1.x client libraries and integrations in InfluxDB OSS {{< current-version >}}. + +To query a mapped bucket with InfluxQL, use the [`/query` 1.x compatibility endpoint](/influxdb/v2.1/reference/api/influxdb-1x/query/). +Include the following in your request: + +- **Request method:** `GET` +- **Headers:** + - **Authorization:** _See [compatibility API authentication](/influxdb/v2.1/reference/api/influxdb-1x/#authentication)_ +- **Query parameters:** + - **db**: 1.x database to query + - **rp**: 1.x retention policy to query _(if no retention policy is specified, InfluxDB uses the default retention policy for the specified database)_ + - **q**: URL-encoded InfluxQL query + +{{% api/url-encode-note %}} + +```sh +curl --get http://localhost:8086/query?db=example-db \ + --header "Authorization: Token YourAuthToken" \ + --data-urlencode "q=SELECT used_percent FROM example-db.example-rp.example-measurement WHERE host=host1" +``` + +By default, the `/query` compatibility endpoint returns results in **JSON**. +To return results as **CSV**, include the `Accept: application/csv` header. + +## InfluxQL support + +InfluxDB OSS {{< current-version >}} supports InfluxQL **read-only** queries. See supported and unsupported queries below. +To learn more about InfluxQL, see [Influx Query Language (InfluxQL)](/{{< latest "influxdb" "v1" >}}/query_language/). + +{{< flex >}} +{{< flex-content >}} +{{% note %}} +##### Supported InfluxQL queries + +- `DELETE`* +- `DROP MEASUREMENT`* +- `EXPLAIN ANALYZE` +- `SELECT` _(read-only)_ +- `SHOW DATABASES` +- `SHOW MEASUREMENTS` +- `SHOW TAG KEYS` +- `SHOW TAG VALUES` +- `SHOW FIELD KEYS` + +\* These commands delete data. +{{% /note %}} +{{< /flex-content >}} +{{< flex-content >}} +{{% warn %}} + +##### Unsupported InfluxQL queries + +- `SELECT INTO` +- `ALTER` +- `CREATE` +- `DROP` _(limited support)_ +- `GRANT` +- `KILL` +- `REVOKE` +{{% /warn %}} +{{< /flex-content >}} +{{< /flex >}} diff --git a/content/influxdb/v2.1/query-data/optimize-queries.md b/content/influxdb/v2.1/query-data/optimize-queries.md new file mode 100644 index 0000000000..497e175d52 --- /dev/null +++ b/content/influxdb/v2.1/query-data/optimize-queries.md @@ -0,0 +1,191 @@ +--- +title: Optimize Flux queries +description: > + Optimize your Flux queries to reduce their memory and compute (CPU) requirements. +weight: 104 +menu: + influxdb_2_1: + name: Optimize queries + parent: Query data +influxdb/v2.1/tags: [query] +--- + +Optimize your Flux queries to reduce their memory and compute (CPU) requirements. + +- [Start queries with pushdowns](#start-queries-with-pushdowns) + - [Avoid processing filters inline](#avoid-processing-filters-inline) +- [Avoid short window durations](#avoid-short-window-durations) +- [Use "heavy" functions sparingly](#use-heavy-functions-sparingly) +- [Use set() instead of map() when possible](#use-set-instead-of-map-when-possible) +- [Balance time range and data precision](#balance-time-range-and-data-precision) +- [Measure query performance with Flux profilers](#measure-query-performance-with-flux-profilers) + +## Start queries with pushdowns +**Pushdowns** are functions or function combinations that push data operations +to the underlying data source rather than operating on data in memory. +Start queries with pushdowns to improve query performance. +Once a non-pushdown function runs, Flux pulls data into memory and runs all +subsequent operations there. + +#### Pushdown functions and function combinations +Most pushdowns are supported when querying an InfluxDB {{< current-version >}} or InfluxDB Cloud data source. +As shown in the following table, a handful of pushdowns are not supported in InfluxDB {{< current-version >}}. + +| Functions | InfluxDB {{< current-version >}} | InfluxDB Cloud | +|:--------- |:------------: |:--------------: | +| **count()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **drop()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **duplicate()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **filter()** {{% req " \*" %}} | {{< icon "check" >}} | {{< icon "check" >}} | +| **fill()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **first()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **keep()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **last()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **max()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **mean()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **min()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **range()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **rename()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **sum()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **window()** | {{< icon "check" >}} | {{< icon "check" >}} | +| _Function combinations_ | | | +| **group()** \|> **count()** | | {{< icon "check" >}} | +| **group()** \|> **first()** | | {{< icon "check" >}} | +| **group()** \|> **last()** | | {{< icon "check" >}} | +| **group()** \|> **max()** | | {{< icon "check" >}} | +| **group()** \|> **min()** | | {{< icon "check" >}} | +| **group()** \|> **sum()** | | {{< icon "check" >}} | +| **window()** \|> **count()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **window()** \|> **first()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **window()** \|> **last()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **window()** \|> **max()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **window()** \|> **min()** | {{< icon "check" >}} | {{< icon "check" >}} | +| **window()** \|> **sum()** | {{< icon "check" >}} | {{< icon "check" >}} | + +{{% caption %}} +{{< req "\*" >}} **filter()** only pushes down when all parameter values are static. +See [Avoid processing filters inline](#avoid-processing-filters-inline). +{{% /caption %}} + +Use pushdown functions and function combinations at the beginning of your query. +Once a non-pushdown function runs, Flux pulls data into memory and runs all +subsequent operations there. + +##### Pushdown functions in use +```js +from(bucket: "example-bucket") + |> range(start: -1h) // + |> filter(fn: (r) => r.sensor == "abc123") // + |> group(columns: ["_field", "host"]) // Pushed to the data source + |> aggregateWindow(every: 5m, fn: max) // + |> filter(fn: (r) => r._value >= 90.0) // + + |> top(n: 10) // Run in memory +``` + +### Avoid processing filters inline +Avoid using mathematic operations or string manipulation inline to define data filters. +Processing filter values inline prevents `filter()` from pushing its operation down +to the underlying data source, so data returned by the +previous function loads into memory. +This often results in a significant performance hit. + +For example, the following query uses [dashboard variables](/influxdb/v2.1/visualize-data/variables/) +and string concatenation to define a region to filter by. +Because `filter()` uses string concatenation inline, it can't push its operation +to the underlying data source and loads all data returned from `range()` into memory. + +```js +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r.region == v.provider + v.region) +``` + +To dynamically set filters and maintain the pushdown ability of the `filter()` function, +use variables to define filter values outside of `filter()`: + +```js +region = v.provider + v.region + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r.region == region) +``` + +## Avoid short window durations +Windowing (grouping data based on time intervals) is commonly used to aggregate and downsample data. +Increase performance by avoiding short window durations. +More windows require more compute power to evaluate which window each row should be assigned to. +Reasonable window durations depend on the total time range queried. + +## Use "heavy" functions sparingly +The following functions use more memory or CPU than others. +Consider their necessity in your data processing before using them: + +- [map()](/{{< latest "flux" >}}/stdlib/universe/map/) +- [reduce()](/{{< latest "flux" >}}/stdlib/universe/reduce/) +- [join()](/{{< latest "flux" >}}/stdlib/universe/join/) +- [union()](/{{< latest "flux" >}}/stdlib/universe/union/) +- [pivot()](/{{< latest "flux" >}}/stdlib/universe/pivot/) + +{{% note %}} +We're continually optimizing Flux and this list may not represent its current state. +{{% /note %}} + +## Use set() instead of map() when possible +[`set()`](/{{< latest "flux" >}}/stdlib/universe/set/), +[`experimental.set()`](/{{< latest "flux" >}}/stdlib/experimental/set/), +and [`map`](/{{< latest "flux" >}}/stdlib/universe/map/) +can each set columns value in data, however **set** functions have performance +advantages over `map()`. + +Use the following guidelines to determine which to use: + +- If setting a column value to a predefined, static value, use `set()` or `experimental.set()`. +- If dynamically setting a column value using **existing row data**, use `map()`. + +#### Set a column value to a static value +The following queries are functionally the same, but using `set()` is more performant than using `map()`. + +```js +data + |> map(fn: (r) => ({ r with foo: "bar" })) + +// Recommended +data + |> set(key: "foo", value: "bar") +``` + +#### Dynamically set a column value using existing row data +```js +data + |> map(fn: (r) => ({ r with foo: r.bar })) +``` + +## Balance time range and data precision +To ensure queries are performant, balance the time range and the precision of your data. +For example, if you query data stored every second and request six months worth of data, +results would include ≈15.5 million points per series. Depending on the number of series returned after `filter()`([cardinality](/influxdb/v2.1/reference/glossary/#series-cardinality)), this can quickly become many billions of points. +Flux must store these points in memory to generate a response. Use [pushdowns](#pushdown-functions-and-function-combinations) to optimize how many points are stored in memory. + +To query data over large periods of time, create a task to [downsample data](/influxdb/v2.1/process-data/common-tasks/downsample-data/), and then query the downsampled data instead. + +## Measure query performance with Flux profilers +Use the [Flux Profiler package](/{{< latest "flux" >}}/stdlib/profiler/) +to measure query performance and append performance metrics to your query output. +The following Flux profilers are available: + +- **query**: provides statistics about the execution of an entire Flux script. +- **operator**: provides statistics about each operation in a query. + +Import the `profiler` package and enable profilers with the `profile.enabledProfilers` option. + +```js +import "profiler" + +option profiler.enabledProfilers = ["query", "operator"] + +// Query to profile +``` + +For more information about Flux profilers, see the [Flux Profiler package](/{{< latest "flux" >}}/stdlib/profiler/). diff --git a/content/influxdb/v2.1/reference/_index.md b/content/influxdb/v2.1/reference/_index.md new file mode 100644 index 0000000000..85629285ef --- /dev/null +++ b/content/influxdb/v2.1/reference/_index.md @@ -0,0 +1,8 @@ +--- +title: InfluxDB reference +description: > + Reference documentation for InfluxDB including release notes, API documentation, + tools, syntaxes, database internals, and more. +--- + +{{< children >}} \ No newline at end of file diff --git a/content/influxdb/v2.1/reference/api/_index.md b/content/influxdb/v2.1/reference/api/_index.md new file mode 100644 index 0000000000..6c563b57fa --- /dev/null +++ b/content/influxdb/v2.1/reference/api/_index.md @@ -0,0 +1,30 @@ +--- +title: InfluxDB v2 API +description: > + The InfluxDB v2 API provides a programmatic interface for interactions with InfluxDB. + Access the InfluxDB API using the `/api/v2/` endpoint. +menu: influxdb_2_1_ref +weight: 3 +influxdb/v2.1/tags: [api] +aliases: + - /influxdb/v2.1/concepts/api/ +--- + +The InfluxDB v2 API provides a programmatic interface for interactions with InfluxDB. +Access the InfluxDB API using the `/api/v2/` endpoint. + +## InfluxDB v2 API documentation +InfluxDB OSS {{< current-version >}} API documentation + +#### View InfluxDB API documentation locally +InfluxDB API documentation is built into the `influxd` service and represents +the API specific to the current version of InfluxDB. +To view the API documentation locally, [start InfluxDB](/influxdb/v2.1/get-started/#start-influxdb) +and visit the `/docs` endpoint in a browser ([localhost:8086/docs](http://localhost:8086/docs)). + +## InfluxDB v1 compatibility API documentation +The InfluxDB v2 API includes [InfluxDB 1.x compatibility endpoints](/influxdb/v2.1/reference/api/influxdb-1x/) +that work with InfluxDB 1.x client libraries and third-party integrations like +[Grafana](https://grafana.com) and others. + +View full v1 compatibility API documentation diff --git a/content/influxdb/v2.1/reference/api/influxdb-1x/_index.md b/content/influxdb/v2.1/reference/api/influxdb-1x/_index.md new file mode 100644 index 0000000000..a0c38fd6b7 --- /dev/null +++ b/content/influxdb/v2.1/reference/api/influxdb-1x/_index.md @@ -0,0 +1,163 @@ +--- +title: InfluxDB 1.x compatibility API +description: > + The InfluxDB v2 API includes InfluxDB 1.x compatibility endpoints that work with + InfluxDB 1.x client libraries and third-party integrations like [Grafana](https://grafana.com) and others. +menu: + influxdb_2_1_ref: + name: 1.x compatibility + parent: InfluxDB v2 API +weight: 104 +influxdb/v2.1/tags: [influxql, query, write] +related: + - /influxdb/v2.1/query-data/influxql + - /influxdb/v2.1/upgrade/v1-to-v2/ +--- + +The InfluxDB v2 API includes InfluxDB 1.x compatibility endpoints that work with +InfluxDB 1.x client libraries and third-party integrations like [Grafana](https://grafana.com) and others. + +View full v1 compatibility API documentation + +## Authentication +InfluxDB {{< current-version >}} requires all query and write requests to be authenticated with an +[API token](/influxdb/v2.1/security/tokens/) or 1.x compatible +credentials. + +* [Authenticate with the Token scheme](#authenticate-with-the-token-scheme) +* [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme) + +### Authenticate with the Token scheme +Token authentication requires the following credential: + +- **token**: InfluxDB [API token](/influxdb/v2.1/security/tokens/) + +Use the `Authorization` header with the `Token` scheme to provide your token to InfluxDB. + +#### Syntax + +```sh +Authorization: Token +``` + +#### Example + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[curl](#curl) +[Node.js](#nodejs) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +{{% get-shared-text "api/v1-compat/auth/oss/token-auth.sh" %}} +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```js +{{% get-shared-text "api/v1-compat/auth/oss/token-auth.js" %}} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +### Authenticate with a username and password scheme + +Use the following authentication schemes with clients that support the InfluxDB 1.x convention of `username` and `password` (that don't support the `Authorization: Token` scheme): + +- [Basic authentication](#basic-authentication) +- [Query string authentication](#query-string-authentication) + +##### Manage credentials + +Username and password schemes require the following credentials: +- **username**: 1.x username (this is separate from the UI login username) +- **password**: 1.x password or InfluxDB API token. + +{{% note %}} +#### Password or Token +{{% api/v1-compat/oss/password-or-token %}} +{{% /note %}} + +For information about creating and managing 1.x-compatible authorizations, see: + +- [`influx v1 auth` command](/influxdb/v2.1/reference/cli/influx/v1/auth/) +- [Manually upgrade – 1.x-compatible authorizations](/influxdb/v2.1/upgrade/v1-to-v2/manual-upgrade/#1x-compatible-authorizations) + +#### Basic authentication + +Use the `Authorization` header with the `Basic` scheme to provide username and +password credentials to InfluxDB. + +{{% api/v1-compat/basic-auth-syntax %}} + +##### Syntax +```sh +Authorization: Basic : +``` + +##### Example + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[curl](#curl) +[Node.js](#nodejs) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +{{% get-shared-text "api/v1-compat/auth/oss/basic-auth.sh" %}} +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```js +{{% get-shared-text "api/v1-compat/auth/oss/basic-auth.js" %}} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +#### Query string authentication +Use InfluxDB 1.x API parameters to provide credentials through the query string. + +{{% note %}} +##### Consider when using query string parameters + +- URL-encode query parameters that may contain whitespace or other special characters. +- Be aware of the [risks](https://owasp.org/www-community/vulnerabilities/Information_exposure_through_query_strings_in_url) when exposing sensitive data through URLs. +{{% /note %}} + +##### Syntax + +```sh + /query/?u=&p= + /write/?u=&p= + ``` + +##### Example + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[curl](#curl) +[Node.js](#nodejs) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +{{< get-shared-text "api/v1-compat/auth/oss/querystring-auth.sh" >}} +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```js +{{< get-shared-text "api/v1-compat/auth/oss/querystring-auth.js" >}} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +##### InfluxQL support + +The compatibility API supports InfluxQL, with the following caveats: + +- The `INTO` clause (e.g. `SELECT ... INTO ...`) is not supported. +- With the exception of [`DELETE`](/{{< latest "influxdb" "v1" >}}/query_language/manage-database/#delete-series-with-delete) and + [`DROP MEASUREMENT`](/{{< latest "influxdb" "v1" >}}/query_language/manage-database/#delete-measurements-with-drop-measurement) queries, which are still allowed, + InfluxQL database management commands are not supported. + +## Compatibility endpoints + +{{< children readmore=true >}} diff --git a/content/influxdb/v2.1/reference/api/influxdb-1x/dbrp.md b/content/influxdb/v2.1/reference/api/influxdb-1x/dbrp.md new file mode 100644 index 0000000000..e6336c58bf --- /dev/null +++ b/content/influxdb/v2.1/reference/api/influxdb-1x/dbrp.md @@ -0,0 +1,58 @@ +--- +title: Database and retention policy mapping +description: > + The database and retention policy (DBRP) mapping service maps InfluxDB 1.x + database and retention policy combinations to InfluxDB Cloud and InfluxDB OSS 2.x buckets. +menu: + influxdb_2_1_ref: + name: DBRP mapping + parent: 1.x compatibility +weight: 302 +related: + - /influxdb/v2.1/reference/api/influxdb-1x/query + - /influxdb/v2.1/reference/api/influxdb-1x/write + - /influxdb/v2.1/api/#tag/DBRPs, InfluxDB v2 API /dbrps endpoint +--- + +The InfluxDB 1.x data model includes [databases](/influxdb/v1.8/concepts/glossary/#database) +and [retention policies](/influxdb/v1.8/concepts/glossary/#retention-policy-rp). +InfluxDB OSS {{< current-version >}} replaces both with [buckets](/influxdb/v2.1/reference/glossary/#bucket). +To support InfluxDB 1.x query and write patterns in InfluxDB OSS {{< current-version >}}, databases and retention +policies are mapped to buckets using the **database and retention policy (DBRP) mapping service**. + +The DBRP mapping service uses the **database** and **retention policy** specified in +[1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/) requests to route operations to a bucket. + +{{% note %}} +To query data in InfluxQL that was written using the 2.x `/write` API, +you must **manually create a DBRP mapping** to map a bucket to a database and retention policy. +For more information, see [Map unmapped buckets](/influxdb/v2.1/query-data/influxql/#map-unmapped-buckets). +{{% /note %}} + +### Default retention policies + +A database can have multiple retention policies with one set as default. +If no retention policy is specified in a query or write request, InfluxDB uses +the default retention policy for the specified database. + +### When writing data + +When writing data using the +[`/write` compatibility endpoint](/influxdb/v2.1/reference/api/influxdb-1x/write/), +the DBRP mapping service checks for a bucket mapped to the database and retention policy: + +- If a mapped bucket is found, data is written to the bucket. +- If an unmapped bucket, InfluxDB returns an error. + See how to [Map unmapped buckets](/influxdb/v2.1/query-data/influxql/#map-unmapped-buckets). + +### When querying data + +When querying data from InfluxDB Cloud and InfluxDB OSS {{< current-version >}} using the +[`/query` compatibility endpoint](/influxdb/v2.1/reference/api/influxdb-1x/query/), +the DBRP mapping service checks for the specified database and retention policy +(if no retention policy is specified, the database's default retention policy is used): + +- If a mapped bucket exists, data is queried from the mapped bucket. +- If no mapped bucket exists, InfluxDB returns an error. See how to [Map unmapped buckets](/influxdb/v2.1/query-data/influxql/#map-unmapped-buckets). + +_For more information on the DBRP mapping API, see the [`/api/v2/dbrps` endpoint documentation](/influxdb/v2.1/api/#tag/DBRPs)._ diff --git a/content/influxdb/v2.1/reference/api/influxdb-1x/query.md b/content/influxdb/v2.1/reference/api/influxdb-1x/query.md new file mode 100644 index 0000000000..a22763bad5 --- /dev/null +++ b/content/influxdb/v2.1/reference/api/influxdb-1x/query.md @@ -0,0 +1,143 @@ +--- +title: /query 1.x compatibility API +list_title: /query +description: > + The `/query` 1.x compatibility endpoint queries InfluxDB Cloud and InfluxDB OSS 2.x using **InfluxQL**. +menu: + influxdb_2_1_ref: + name: /query + parent: 1.x compatibility +weight: 301 +influxdb/v2.1/tags: [influxql, query] +list_code_example: | + 
    +  GET http://localhost:8086/query
+
    +related: + - /influxdb/v2.1/query-data/influxql +--- + +The `/query` 1.x compatibility endpoint queries InfluxDB Cloud and InfluxDB OSS {{< current-version >}} using **InfluxQL**. +Use the `GET` request method to query data from the `/query` endpoint. + +
    +GET http://localhost:8086/query
+
    + +The `/query` compatibility endpoint uses the **database** and **retention policy** +specified in the query request to map the request to an InfluxDB bucket. +For more information, see [Database and retention policy mapping](/influxdb/v2.1/reference/api/influxdb-1x/dbrp). + +{{% note %}} +If you have an existing bucket that doesn't follow the **database/retention-policy** naming convention, +you **must** [manually create a database and retention policy mapping](/influxdb/v2.1/query-data/influxql/#map-unmapped-buckets) +to query that bucket with the `/query` compatibility API. +{{% /note %}} + +## Authentication + +Use one of the following authentication methods: +* **token authentication** +* **basic authentication with username and password** +* **query string authentication with username and password** + +_For more information, see [Authentication](/influxdb/v2.1/reference/api/influxdb-1x/#authentication)._ + +## Query string parameters + +### u +(Optional) The 1.x **username** to authenticate the request. +_See [query string authentication](/influxdb/v2.1/reference/api/influxdb-1x/#query-string-authentication)._ + +### p +(Optional) The 1.x **password** to authenticate the request. +_See [query string authentication](/influxdb/v2.1/reference/api/influxdb-1x/#query-string-authentication)._ + +### db +({{< req >}}) The **database** to query data from. +This is mapped to an InfluxDB [bucket](/influxdb/v2.1/reference/glossary/#bucket). +_See [Database and retention policy mapping](/influxdb/v2.1/reference/api/influxdb-1x/dbrp/)._ + +### rp +The **retention policy** to query data from. +This is mapped to an InfluxDB [bucket](/influxdb/v2.1/reference/glossary/#bucket). +_See [Database and retention policy mapping](/influxdb/v2.1/reference/api/influxdb-1x/dbrp/)._ + +### q +({{< req >}}) The **InfluxQL** query to execute. +To execute multiple queries, delimit queries with a semicolon (`;`). + +### epoch +Return results with [Unix timestamps](/influxdb/v2.1/reference/glossary/#unix-timestamp) +(also known as epoch timestamps) in the specified precision instead of +[RFC3339 timestamps](/influxdb/v2.1/reference/glossary/#rfc3339-timestamp) with nanosecond precision. +The following precisions are available: + +- `ns` - nanoseconds +- `u` or `µ` - microseconds +- `ms` - milliseconds +- `s` - seconds +- `m` - minutes +- `h` - hours + +## Query examples + +- [Query using basic authentication](#query-using-basic-authentication) +- [Query a non-default retention policy](#query-a-non-default-retention-policy) +- [Execute multiple queries](#execute-multiple-queries) +- [Return query results with millisecond Unix timestamps](#return-query-results-with-millisecond-unix-timestamps) +- [Execute InfluxQL queries from a file](#execute-influxql-queries-from-a-file) + +##### Query using basic authentication +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[curl](#curl) +[Node.js](#nodejs) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +{{% get-shared-text "api/v1-compat/auth/oss/basic-auth.sh" %}} +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```js +{{% get-shared-text "api/v1-compat/auth/oss/basic-auth.js" %}} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +##### Query a non-default retention policy +```sh +curl --get http://localhost:8086/query \ + --user "OneDotXUsername":"myPasswordOrAuthToken" \ + --data-urlencode "db=mydb" \ + --data-urlencode "rp=customrp" \ + --data-urlencode "q=SELECT used_percent FROM mem WHERE host=host1" +``` + +##### Execute multiple queries +```sh +curl --get http://localhost:8086/query \ + --header "Authorization: Token YourAuthToken" \ + --data-urlencode "db=mydb" \ + --data-urlencode "q=SELECT * FROM mem WHERE host=host1;SELECT mean(used_percent) FROM mem WHERE host=host1 GROUP BY time(10m)" +``` + +##### Return query results with millisecond Unix timestamps +```sh +curl --get http://localhost:8086/query \ + --header "Authorization: Token YourAuthToken" \ + --data-urlencode "db=mydb" \ + --data-urlencode "rp=myrp" \ + --data-urlencode "q=SELECT used_percent FROM mem WHERE host=host1" \ + --data-urlencode "epoch=ms" +``` + +##### Execute InfluxQL queries from a file +```sh +curl --get http://localhost:8086/query \ + --header "Authorization: Token YourAuthToken" \ + --data-urlencode "db=mydb" \ + --form "q=@path/to/influxql.txt" \ + --form "async=true" +``` diff --git a/content/influxdb/v2.1/reference/api/influxdb-1x/write.md b/content/influxdb/v2.1/reference/api/influxdb-1x/write.md new file mode 100644 index 0000000000..0b4f03e273 --- /dev/null +++ b/content/influxdb/v2.1/reference/api/influxdb-1x/write.md @@ -0,0 +1,133 @@ +--- +title: /write 1.x compatibility API +list_title: /write +description: > + The `/write` 1.x compatibility endpoint writes data to InfluxDB Cloud and + InfluxDB OSS 2.x using patterns from the InfluxDB 1.x `/write` API endpoint. +menu: + influxdb_2_1_ref: + name: /write + parent: 1.x compatibility +weight: 301 +influxdb/v2.1/tags: [write] +list_code_example: | + 
    +  POST http://localhost:8086/write
+
    +related: + - /influxdb/v2.1/reference/syntax/line-protocol +--- + +The `/write` 1.x compatibility endpoint writes data to InfluxDB Cloud and InfluxDB OSS {{< current-version >}} +using patterns from the InfluxDB 1.x `/write` API endpoint. +Use the `POST` request method to write [line protocol](/influxdb/v2.1/reference/syntax/line-protocol/) +to the `/write` endpoint. + +
    +POST http://localhost:8086/write
+
    + +{{% note %}} +If you have an existing bucket that doesn't follow the **database/retention-policy** naming convention, +you **must** [manually create a database and retention policy mapping](/influxdb/v2.1/query-data/influxql/#map-unmapped-buckets) +to write data to that bucket with the `/write` compatibility API. +{{% /note %}} + +## Authentication + +Use one of the following authentication methods: +* **token authentication** +* **basic authentication with username and password** +* **query string authentication with username and password** + +_For more information, see [Authentication](/influxdb/v2.1/reference/api/influxdb-1x/#authentication)._ + +## Request body +Include your line protocol in the request body. +**Binary encode** the line protocol to prevent unintended formatting. +The examples [below](#write-examples) use the curl `--data-binary` flag to binary +encode the line protocol. + +## Query string parameters + +### u +(Optional) The 1.x **username** to authenticate the request. +_See [query string authentication](/influxdb/v2.1/reference/api/influxdb-1x/#query-string-authentication)._ + +### p +(Optional) The 1.x **password** to authenticate the request. +_See [query string authentication](/influxdb/v2.1/reference/api/influxdb-1x/#query-string-authentication)._ + +### db +({{< req >}}) The **database** to write data to. +This is mapped to an InfluxDB [bucket](/influxdb/v2.1/reference/glossary/#bucket). +_See [Database and retention policy mapping](/influxdb/v2.1/reference/api/influxdb-1x/dbrp/)._ + +### rp +The **retention policy** to write data to. +This is mapped to an InfluxDB [bucket](/influxdb/v2.1/reference/glossary/#bucket). +_See [Database and retention policy mapping](/influxdb/v2.1/reference/api/influxdb-1x/dbrp/)._ + +### precision +The precision of [Unix timestamps](/influxdb/v2.1/reference/glossary/#unix-timestamp) in the line protocol. +Default is nanosconds (`ns`). +The following precisions are available: + +- `ns` - nanoseconds +- `u` or `µ` - microseconds +- `ms` - milliseconds +- `s` - seconds +- `m` - minutes +- `h` - hours + +## Write examples + +- [Write data using basic authentication](#write-data-using-basic-authentication) +- [Write data to a non-default retention policy](#write-data-to-a-non-default-retention-policy) +- [Write multiple lines of line protocol](#write-multiple-lines-of-line-protocol) +- [Write data with millisecond Unix timestamps](#write-data-with-millisecond-unix-timestamps) +- [Use curl to write data from a file](#use-curl-to-write-data-from-a-file) + +##### Write data using basic authentication +```sh +curl --request POST http://localhost:8086/write?db=mydb \ + --user "myusername:PasswordOrAuthToken" \ + --data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000" +``` + +##### Write data using token authentication +```sh +curl --request POST http://localhost:8086/write?db=mydb \ + --header "Authorization: Token YourAuthToken" \ + --data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000" +``` + +##### Write data to a non-default retention policy +```sh +curl --request POST http://localhost:8086/write?db=mydb&rp=customrp \ + --user "myusername:PasswordOrAuthToken" \ + --data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000" +``` + +##### Write multiple lines of line protocol +```sh +curl --request POST http://localhost:8086/write?db=mydb \ + --header "Authorization: Token YourAuthToken" \ + --data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000 +measurement,host=host2 field1=14i,field2=12.7 1577836800000000000 +measurement,host=host3 field1=5i,field2=6.8 1577836800000000000" +``` + +##### Write data with millisecond Unix timestamps +```sh +curl --request POST http://localhost:8086/write?db=mydb&precision=ms \ + --header "Authorization: Token YourAuthToken" \ + --data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000" +``` + +##### Use curl to write data from a file +```sh +curl --request POST http://localhost:8086/write?db=mydb \ + --header "Authorization: Token YourAuthToken" \ + --data-binary @path/to/line-protocol.txt +``` diff --git a/content/influxdb/v2.1/reference/cli/_index.md b/content/influxdb/v2.1/reference/cli/_index.md new file mode 100644 index 0000000000..337889139d --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/_index.md @@ -0,0 +1,18 @@ +--- +title: Command line tools +seotitle: Command line tools for managing InfluxDB +description: > + InfluxDB provides command line tools designed to aid in managing and working + with InfluxDB from the command line. +influxdb/v2.1/tags: [cli] +menu: + influxdb_2_1_ref: + name: Command line tools +weight: 4 +--- + +InfluxDB provides command line tools designed to aid in managing and working +with InfluxDB from the command line. +The following command line interfaces (CLIs) are available: + +{{< children >}} diff --git a/content/influxdb/v2.1/reference/cli/influx/_index.md b/content/influxdb/v2.1/reference/cli/influx/_index.md new file mode 100644 index 0000000000..8267a3c0cf --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/_index.md @@ -0,0 +1,133 @@ +--- +title: influx - InfluxDB command line interface +seotitle: influx - InfluxDB command line interface +description: > + The `influx` CLI includes commands to manage many aspects of InfluxDB, + including buckets, organizations, users, tasks, etc. +menu: + influxdb_2_1_ref: + name: influx + parent: Command line tools +weight: 101 +influxdb/v2.1/tags: [cli] +related: + - /influxdb/v2.1/tools/influx-cli/ +--- + +The `influx` command line interface (CLI) includes commands to manage many aspects of InfluxDB, +including buckets, organizations, users, tasks, etc. + +{{% oss-only %}} + +{{% note %}} +#### InfluxDB OSS and influx CLI versions +Beginning with **InfluxDB 2.1**, the `influx` CLI is packaged and versioned separately +from InfluxDB. +InfluxDB and `influx` CLI versions may differ, but compatibility is noted for each command. +{{% /note %}} + +{{% /oss-only %}} + +## Download and install the influx CLI +Download and install the influx CLI + +### Provide required authentication credentials +To avoid having to pass your InfluxDB **host**, **API token**, and **organization** +with each command, store them in an `influx` CLI configuration (config). +`influx` commands that require these credentials automatically retrieve these +credentials from the active config. + +Use the [`influx config create` command](/influxdb/v2.1/reference/cli/influx/config/create/) +to create an `influx` CLI config and set it as active: + +```sh +influx config create --config-name \ + --host-url http://localhost:8086 \ + --org \ + --token \ + --active +``` + +For more information about managing CLI configurations, see the +[`influx config` documentation](/influxdb/v2.1/reference/cli/influx/config/). + +## Usage + +``` +influx [flags] +influx [command] +``` + +## Commands + +| Command | Description | +| :------------------------------------------------------------------ | :------------------------------------------------------------------------- | +| [apply](/influxdb/v2.1/reference/cli/influx/apply/) | Apply an InfluxDB template | +| [auth](/influxdb/v2.1/reference/cli/influx/auth/) | API token management commands | +| [backup](/influxdb/v2.1/reference/cli/influx/backup/) | Back up data _(InfluxDB OSS only)_ | +| [bucket](/influxdb/v2.1/reference/cli/influx/bucket/) | Bucket management commands | +| [bucket-schema](/influxdb/v2.1/reference/cli/influx/bucket-schema/) | Manage InfluxDB bucket schemas _(InfluxDB Cloud only)_ | +| [completion](/influxdb/v2.1/reference/cli/influx/completion/) | Generate completion scripts | +| [config](/influxdb/v2.1/reference/cli/influx/config/) | Configuration management commands | +| [dashboards](/influxdb/v2.1/reference/cli/influx/dashboards/) | List dashboards | +| [delete](/influxdb/v2.1/reference/cli/influx/delete/) | Delete points from InfluxDB | +| [export](/influxdb/v2.1/reference/cli/influx/export/) | Export resources as a template | +| [help](/influxdb/v2.1/reference/cli/influx/help/) | Help about any command | +| [org](/influxdb/v2.1/reference/cli/influx/org/) | Organization management commands | +| [ping](/influxdb/v2.1/reference/cli/influx/ping/) | Check the InfluxDB `/health` endpoint | +| [query](/influxdb/v2.1/reference/cli/influx/query/) | Execute a Flux query | +| [restore](/influxdb/v2.1/reference/cli/influx/restore/) | Restore backup data _(InfluxDB OSS only)_ | +| [secret](/influxdb/v2.1/reference/cli/influx/secret/) | Manage secrets | +| [setup](/influxdb/v2.1/reference/cli/influx/setup/) | Create default username, password, org, bucket, etc. _(InfluxDB OSS only)_ | +| [stacks](/influxdb/v2.1/reference/cli/influx/stacks/) | Manage InfluxDB stacks | +| [task](/influxdb/v2.1/reference/cli/influx/task/) | Task management commands | +| [telegrafs](/influxdb/v2.1/reference/cli/influx/telegrafs/) | Telegraf configuration management commands | +| [template](/influxdb/v2.1/reference/cli/influx/template/) | Summarize and validate an InfluxDB template | +| [user](/influxdb/v2.1/reference/cli/influx/user/) | User management commands | +| [v1](/influxdb/v2.1/reference/cli/influx/v1/) | Work with the v1 compatibility API | +| [version](/influxdb/v2.1/reference/cli/influx/version/) | Print the influx CLI version | +| [write](/influxdb/v2.1/reference/cli/influx/write/) | Write points to InfluxDB | + +## Flags + +| Flag | | Description | +|:---- |:--- |:----------- | +| `-h` | `--help` | Help for the `influx` command | + +### Flag patterns and conventions +The `influx` CLI uses the following patterns and conventions: + +- [Mapped environment variables](#mapped-environment-variables) +- [Shorthand and longhand flags](#shorthand-and-longhand-flags) +- [Flag input types](#flag-input-types) + +#### Mapped environment variables +`influx` CLI flags mapped to environment variables are listed in the **Mapped to** column. +Mapped flags inherit the value of the environment variable. +To override environment variables, set the flag explicitly in your command. + +#### Shorthand and longhand flags +Many `influx` CLI flags support both shorthand and longhand forms. + +- **shorthand:** a shorthand flag begins with a single hyphen followed by a single letter (for example: `-c`). +- **longhand:** a longhand flag starts with two hyphens followed by a multi-letter, + hyphen-spaced flag name (for example: `--active-config`). + +Commands can use both shorthand and longhand flags in a single execution. + +#### Flag input types +`influx` CLI flag input types are listed in each the table of flags for each command. +Flags support the following input types: + +##### string +Text string, but the flag can be used **only once** per command execution. + +##### stringArray +Single text string, but the flag can be used **multiple times** per command execution. + +##### integer +Sequence of digits representing an integer value. + +##### duration +Length of time represented by an integer and a duration unit +(`1ns`, `1us`, `1µs`, `1ms`, `1s`, `1m`, `1h`, `1d`, `1w`). diff --git a/content/influxdb/v2.1/reference/cli/influx/apply/_index.md b/content/influxdb/v2.1/reference/cli/influx/apply/_index.md new file mode 100644 index 0000000000..67bc0f161a --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/apply/_index.md @@ -0,0 +1,132 @@ +--- +title: influx apply +description: The `influx apply` command applies InfluxDB templates. +menu: + influxdb_2_1_ref: + name: influx apply + parent: influx +weight: 101 +aliases: + - /influxdb/v2.1/reference/cli/influx/pkg/ +influxdb/v2.1/tags: [templates] +related: + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +--- + +The `influx apply` command applies InfluxDB templates. +_For information about finding and using InfluxDB templates, see +[Use InfluxDB templates](/influxdb/v2.1/influxdb-templates/use/)._ + +## Usage +``` +influx apply [flags] +``` + +## Flags +| Flag | | Description | Input Type | {{< cli/mapped >}} | +|:-----|:--------------------------|:--------------------------------------------------------------------------------------------|:-----------|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| | `--disable-color` | Disable color in output | | | +| | `--disable-table-borders` | Disable table borders | | | +| `-e` | `--encoding` | Encoding of the input stream | string | | +| | `--env-ref` | Environment references to provide with the template (format: `--env-ref=REF_KEY=REF_VALUE`) | string | | +| `-f` | `--file` | Path to template file (supports HTTP(S) URLs or file paths) | string | | +| | `--filter` | Resources to skip when applying the template (filter by `kind` or `resource`) | string | | +| | `--force` | Ignore warnings about destructive changes | | | +| `-h` | `--help` | Help for the `apply` command | | | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--json` | Output data as JSON | | `INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name that owns the bucket (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID that owns the bucket (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| `-q` | `--quiet` | Disable output printing | | | +| `-R` | `--recurse` | Recurse through files in the directory specified in `-f`, `--file` | | | +| | `--secret` | Secrets to provide with the template (format: `--secret=SECRET_KEY=SECRET_VALUE`) | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| | `--stack-id` | Stack ID to associate when applying the template | string | | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples: how to apply a template or stack + +{{< cli/influx-creds-note >}} + +- [from a file](#apply-a-template-from-a-file) +- [from a URL](#apply-a-template-from-a-url) +- [from a stack that has associated templates](#apply-a-stack-that-has-associated-templates) +- [a template to a stack](#apply-a-template-to-a-stack) +- [multiple template files together](#apply-multiple-template-files-together) +- [a template from stdin](#apply-a-template-from-stdin) +- [all templates in a directory](#apply-all-templates-in-a-directory) +- [recursively from a directory](#recursively-apply-templates-from-a-directory) +- [from multiple sources](#apply-templates-from-multiple-sources) +- [skip resources](#apply-a-template-but-skip-resources) + +##### Apply a template from a file +```sh +influx apply --file path/to/template.json +``` + +##### Apply a template from a URL +```sh +influx apply --file https://raw.githubusercontent.com/influxdata/community-templates/master/docker/docker.yml +``` + +##### Apply a stack that has associated templates +To apply all templates associated with a stack ID to a new stack: + +```sh +influx apply --stack-id $STACK_ID +``` + +##### Apply a template to a stack +```sh +influx apply --file path/to/template.json --stack-id $STACK_ID +``` + +##### Apply multiple template files together +```sh +influx apply \ + --file path/to/template_1.json \ + --file path/to/template_2.yml +``` + +##### Apply a template from stdin +```sh +cat template.json | influx apply --encoding json +``` + +##### Apply all templates in a directory +```sh +influx apply --file path/to/template_directory +``` + +##### Recursively apply templates from a directory +```sh +influx apply --recurse --file path/to/template_directory +``` + +##### Apply templates from multiple sources +```sh +influx apply \ + --file path/to/template.yml + --file path/to/templates_directory + --file https://example.com/template.json +``` + +##### Apply a template, but skip resources +```sh +# The following example skips all buckets and the dashboard +# whose metadata.name field matches "example-dashboard". + +# Filter format: +# --filter=kind=Bucket +# --filter=resource=Label:$Label_TMPL_NAME + +influx apply \ + --file path/to/template.yml \ + --filter kind=Bucket \ + --filter resource=Dashboard:example-dashboard +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/auth/_index.md b/content/influxdb/v2.1/reference/cli/influx/auth/_index.md new file mode 100644 index 0000000000..45844765fd --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/auth/_index.md @@ -0,0 +1,41 @@ +--- +title: influx auth +description: The `influx auth` command and its subcommands manage API tokens in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx auth + parent: influx +weight: 101 +influxdb/v2.1/tags: [authentication] +cascade: + related: + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +cascade: + metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +--- + +The `influx auth` command and its subcommands manage API tokens in InfluxDB. + +## Usage +``` +influx auth [flags] +influx auth [command] +``` + +#### Command aliases +`auth`, `authorization` + +## Subcommands +| Subcommand | Description | +|:---------- |:----------- | +| [active](/influxdb/v2.1/reference/cli/influx/auth/active) | Activate API token | +| [create](/influxdb/v2.1/reference/cli/influx/auth/create) | Create API token | +| [delete](/influxdb/v2.1/reference/cli/influx/auth/delete) | Delete API token | +| [list](/influxdb/v2.1/reference/cli/influx/auth/list) | List API tokens | +| [inactive](/influxdb/v2.1/reference/cli/influx/auth/inactive) | Inactivate API token | + +## Flags +| Flag | | Description | +|:---- |:--- |:----------- | +| `-h` | `--help` | Help for the `auth` command | diff --git a/content/influxdb/v2.1/reference/cli/influx/auth/active.md b/content/influxdb/v2.1/reference/cli/influx/auth/active.md new file mode 100644 index 0000000000..e7a4fc28a6 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/auth/active.md @@ -0,0 +1,40 @@ +--- +title: influx auth active +description: The `influx auth active` command sets an API token to active in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx auth active + parent: influx auth +weight: 201 +--- + +The `influx auth active` command activates an API token. +Only active tokens authorize access to InfluxDB. + +## Usage +``` +influx auth active [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `active` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| `-i` | `--id` | ({{< req >}}) API token ID | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Example + +{{< cli/influx-creds-note >}} + +##### Activate an API token +```sh +influx auth active --id 06c86c40a9f36000 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/auth/create.md b/content/influxdb/v2.1/reference/cli/influx/auth/create.md new file mode 100644 index 0000000000..09e71bd802 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/auth/create.md @@ -0,0 +1,140 @@ +--- +title: influx auth create +description: The `influx auth create` command creates an API token in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx auth create + parent: influx auth +weight: 201 +updated_in: CLI v2.2.0 +--- + +The `influx auth create` command creates an API token in InfluxDB. + +## Usage +``` +influx auth create [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:--------------------------------|:----------------------------------------------------------------------|:-----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--all-access` | Grants all permissions in a single organization | | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-d` | `--description` | API token description | string | | +| `-h` | `--help` | Help for the `create` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| | `--operator` | _(InfluxDB OSS only)_ Grants all permissions in all organizations | string | | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--read-bucket` | Grant permission to read a specified bucket ID | stringArray | | +| | `--read-buckets` | Grant permission to read **all** organization buckets | | | +| | `--read-checks` | Grant permission to read checks | | | +| | `--read-dashboards` | Grant permission to read dashboards | | | +| | `--read-dbrps` | Grant permission to read database retention policy mappings | | | +| | `--read-notificationEndpoints` | Grant permission to read notificationEndpoints | | | +| | `--read-notificationRules` | Grant permission to read notificationRules | | | +| | `--read-orgs` | Grant permission to read organizations | | | +| | `--read-tasks` | Grant permission to read tasks | | | +| | `--read-telegrafs` | Grant permission to read Telegraf configurations | | | +| | `--read-user` | Grant permission to read organization users | | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | +| `-u` | `--user` | Username | string | | +| | `--write-bucket` | Grant permission to write to specified a bucket ID | stringArray | | +| | `--write-buckets` | Grant permission to create and update **all** organization buckets | | | +| | `--write-checks` | Grant permission to create checks | | | +| | `--write-dashboards` | Grant permission to create and update dashboards | | | +| | `--write-dbrps` | Grant permission to create database retention policy mappings | | | +| | `--write-notificationEndpoints` | Grant permission to create notificationEndpoints | | | +| | `--write-notificationRules` | Grant permission to create notificationRules | | | +| | `--write-orgs` | Grant permission to create and update organizations | | | +| | `--write-tasks` | Grant permission to create and update tasks | | | +| | `--write-telegrafs` | Grant permission to create and update Telegraf configurations | | | +| | `--write-user` | Grant permission to create and update organization users | | | + +## Examples + +{{< cli/influx-creds-note >}} + +- [Create an All-Access API token](#create-an-all-access-api-token) {{% oss-only %}} or [Create an Operator API token](#create-an-operator-api-token){{% /oss-only %}} +- [Create an API token with specified read and write permissions](#create-an-api-token-with-specified-read-and-write-permissions) +- [Create a token with read and write access to specific buckets](#create-an-api-token-with-read-and-write-access-to-specific-buckets) +- [Create a read-only API token](#create-a-read-only-api-token) + +### Create an All-Access API token + +Create an [All-Access token](/influxdb/cloud/security/tokens/#all-access-token) to grant permissions to all resources in an organization. + +```sh +influx auth create \ + --all-access +``` + +{{% oss-only %}} + +### Create an Operator API token + +Create an [Operator token](/influxdb/v2.0/security/tokens/#operator-token) to grant permissions to all resources in all organizations. + +```sh +influx auth create \ + --operator +``` +{{% /oss-only %}} + +### Create an API token with specified read and write permissions + +```sh +influx auth create \ + --read-buckets \ + --read-checks \ + --read-dashboards \ + --read-dbrps \ + --read-notificationEndpoints \ + --read-notificationRules \ + --read-orgs \ + --read-tasks \ + --read-telegrafs \ + --read-user \ + --write-buckets \ + --write-checks \ + --write-dashboards \ + --write-dbrps \ + --write-notificationEndpoints \ + --write-notificationRules \ + --write-orgs \ + --write-tasks \ + --write-telegrafs \ + --write-user +``` + +### Create an API token with read and write access to specific buckets + +```sh +influx auth create \ + --read-bucket 0000000000000001 \ + --read-bucket 0000000000000002 \ + --write-bucket 0000000000000001 \ + --write-bucket 0000000000000002 +``` + +### Create a read-only API token + +```sh +influx auth create \ + --read-buckets \ + --read-checks \ + --read-dashboards \ + --read-dbrps \ + --read-notificationEndpoints \ + --read-notificationRules \ + --read-orgs \ + --read-tasks \ + --read-telegrafs \ + --read-user +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/auth/delete.md b/content/influxdb/v2.1/reference/cli/influx/auth/delete.md new file mode 100644 index 0000000000..26e0a866ae --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/auth/delete.md @@ -0,0 +1,39 @@ +--- +title: influx auth delete +description: The `influx auth delete` command deletes an API token from InfluxDB. +menu: + influxdb_2_1_ref: + name: influx auth delete + parent: influx auth +weight: 201 +--- + +The `influx auth delete` command deletes an API token from InfluxDB. + +## Usage +``` +influx auth delete [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `delete` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-i` | `--id` | ({{< req >}}) API token ID | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Delete an API token +```sh +influx auth delete --id 06c86c40a9f36000 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/auth/inactive.md b/content/influxdb/v2.1/reference/cli/influx/auth/inactive.md new file mode 100644 index 0000000000..18cb6edd75 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/auth/inactive.md @@ -0,0 +1,47 @@ +--- +title: influx auth inactive +description: The `influx auth inactive` command inactivates an API token in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx auth inactive + parent: influx auth +weight: 201 +--- + +The `influx auth inactive` command inactivates an API token in InfluxDB. +Inactive tokens **do not** authorize access to InfluxDB. + +To temporarily disable client access to InfluxDB, inactivate the authentication +token the client is using rather than delete the token. +If you delete the token, you have to generate a new token and update the client +with the new token. +By setting a token to inactive, you can [activate the token](/influxdb/v2.1/reference/cli/influx/auth/active/) +to grant the client access without having to modify the client. + +## Usage +``` +influx auth inactive [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `inactive` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-i` | `--id` | ({{< req >}}) API token ID | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Inactivate an API token +```sh +influx auth inactive --id 06c86c40a9f36000 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/auth/list.md b/content/influxdb/v2.1/reference/cli/influx/auth/list.md new file mode 100644 index 0000000000..69c1bbd0e3 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/auth/list.md @@ -0,0 +1,53 @@ +--- +title: influx auth list +description: The `influx auth list` command lists API tokens in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx auth list + parent: influx auth +weight: 201 +aliases: + - /influxdb/v2.1/reference/cli/influx/auth/find +--- + +The `influx auth list` command lists and searches API tokens in InfluxDB. + +## Usage +``` +influx auth list [flags] +``` + +#### Command aliases +`list`, `ls`, `find` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `list` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-i` | `--id` | API token ID | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | +| `-u` | `--user` | Username | string | | +| | `--user-id` | User ID | string | | + +## Examples + +{{< cli/influx-creds-note >}} + +##### List all API tokens +```sh +influx auth list +``` + +##### List API tokens associated with a user +```sh +influx auth list --user username +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/backup/_index.md b/content/influxdb/v2.1/reference/cli/influx/backup/_index.md new file mode 100644 index 0000000000..655129790c --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/backup/_index.md @@ -0,0 +1,66 @@ +--- +title: influx backup +description: The `influx backup` command backs up data stored in InfluxDB to a specified directory. +menu: + influxdb_2_1_ref: + name: influx backup + parent: influx +weight: 101 +influxdb/v2.1/tags: [backup] +related: + - /influxdb/v2.1/backup-restore/backup/ + - /influxdb/v2.1/reference/cli/influx/restore/ + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +updated_in: CLI v2.0.2 +--- + +The `influx backup` command backs up data stored in InfluxDB to a specified directory. + +## Usage +``` +influx backup [flags] path +``` + +## Flags + +| Flag | | Description | Input type | {{< cli/mapped >}} | +|------|-------------------|------------------------------------------------------------------------------------------------------------|------------|-----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--bucket-id` | ID of the bucket to back up from (mutually exclusive with `--bucket`) | string | | +| `-b` | `--bucket` | Name of the bucket to back up from (mutually exclusive with `--bucket-id`) | string | | +| | `--compression` | By default, `gzip` argument enables compression on downloaded files. Set to `none` to disable compression. | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `backup` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default: `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | string | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +- [Back up all data to a directory](#back-up-all-data-to-a-directory) +- [Back up all data to the current working directory](#back-up-all-data-to-the-current-working-directory) +- [Back up a specific bucket to a directory](#back-up-a-specific-bucket-to-a-directory) + +##### Back up all data to a directory +```sh +influx backup /path/to/backup/dir/ +``` + +##### Back up all data to the current working directory +```sh +influx backup ./ +``` + +##### Back up a specific bucket to a directory +```sh +influx backup --bucket example-bucket /path/to/backup/dir/ +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/bucket-schema/_index.md b/content/influxdb/v2.1/reference/cli/influx/bucket-schema/_index.md new file mode 100644 index 0000000000..719768ca1d --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/bucket-schema/_index.md @@ -0,0 +1,47 @@ +--- +title: influx bucket-schema +description: The `influx bucket-schema` command and its subcommands manage schemas of buckets in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx bucket-schema + parent: influx +weight: 101 +influxdb/v2.1/tags: [buckets, bucket-schema] +cascade: + related: + - /influxdb/cloud/organizations/buckets/bucket-schema + - /influxdb/cloud/organizations/buckets/ + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.1.0+, InfluxDB Cloud only] + prepend: + block: cloud + content: | + #### Works with InfluxDB Cloud bucket schemas + `influx bucket-schema` and its subcommands work with [InfluxDB Cloud bucket schemas](/influxdb/cloud/organizations/buckets/bucket-schema). + This feature is not available in InfluxDB OSS v2.1. +--- + +The `influx bucket-schema` command and its subcommands manage +schemas for InfluxDB buckets. + +## Usage + +``` +influx bucket-schema [flags] +influx bucket-schema [command] +``` + +## Subcommands + +| Subcommand | Description | +| :----------------------------------------------------------------- | :--------------------- | +| [create](/influxdb/v2.1/reference/cli/influx/bucket-schema/create) | Create a bucket schema | +| [list](/influxdb/v2.1/reference/cli/influx/bucket-schema/list) | List bucket schemas | +| [update](/influxdb/v2.1/reference/cli/influx/bucket-schema/update) | Update a bucket schema | + +## Flags + +| Flag | | Description | +| :--- | :------- | :----------------------------------- | +| `-h` | `--help` | Help for the `bucket-schema` command | diff --git a/content/influxdb/v2.1/reference/cli/influx/bucket-schema/create.md b/content/influxdb/v2.1/reference/cli/influx/bucket-schema/create.md new file mode 100644 index 0000000000..5cd2cbd97f --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/bucket-schema/create.md @@ -0,0 +1,90 @@ +--- +title: influx bucket-schema create +description: The `influx bucket-schema create` command sets the schema for a measurement in an InfluxDB bucket that has the `explicit` schema-type. +menu: + influxdb_2_1_ref: + name: influx bucket-schema create + parent: influx bucket-schema +weight: 201 +related: + - /influxdb/cloud/organizations/buckets/bucket-schema +--- + +The `influx bucket-schema create` command sets the schema for a measurement in +an InfluxDB bucket that has the [`explicit` schema-type](/influxdb/cloud/reference/cli/influx/bucket/create/#create-a-bucket-with-an-explicit-schema). + +## Usage + +```sh +influx bucket-schema create [flags] +``` + +## Flags + +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:--------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| `-n` | `--bucket` | ({{< req >}}) Bucket name (mutually exclusive with `--bucket-id`) | string | | +| `-i` | `--bucket-id` | ({{< req >}}) Bucket ID (mutually exclusive with `--bucket`) | string | | +| | `--columns-file` | ({{< req >}}) Path to column definitions file. For more information, see [Create a columns file](/influxdb/cloud/reference/cli/influx/bucket-schema/create/#create-a-columns-file). | string | | +| | `--columns-format` | Columns file format (`csv`, `ndjson`, `json`, default: `auto`). For more information, see [Create a schema with columns format](#create-a-schema-with-columns-format) | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-x` | `--extended-output` | Print column information for each measurement schema (default: false) | | | +| `-h` | `--help` | Help for the `create` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-n` | `--name` | ({{< req >}}) Measurement name | string | | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + + +## Examples + +{{< cli/influx-creds-note >}} + +- [Create a schema using the influx CLI](#create-a-schema-using-the-influx-cli) +- [Create a schema and print column information](#create-a-schema-and-print-column-information) +- [Create a schema with columns format](#create-a-schema-with-columns-format) + +### Create a schema using the influx CLI + +```sh +influx bucket-schema create \ + --bucket example-bucket \ + --name temperature \ + --columns-file columns.csv +``` + +### Create a schema and print column information + +```sh +influx bucket-schema create \ + --bucket example-bucket \ + --name cpu \ + --columns-file columns.csv \ + --extended-output +``` + +### Create a schema with columns format + +By default, InfluxDB attempts to detect the **columns file** format. +If your file's extension doesn't match the format, set the format with the [`columns-format` flag](/influxdb/cloud/reference/cli/influx/bucket-schema/create). + +```sh +influx bucket-schema create \ + --bucket example-bucket \ + --name cpu \ + --columns-file columns.json \ + --columns-format ndjson +``` + +```sh +influx bucket-schema create \ + --bucket example-bucket \ + --name cpu \ + --columns-file columns.txt \ + --columns-format csv +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/bucket-schema/list.md b/content/influxdb/v2.1/reference/cli/influx/bucket-schema/list.md new file mode 100644 index 0000000000..2c8e49aef0 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/bucket-schema/list.md @@ -0,0 +1,59 @@ +--- +title: influx bucket-schema list +description: The `influx bucket-schema list` command lists the schemas of an InfluxDB bucket that has the `explicit` schema-type. +menu: + influxdb_2_1_ref: + name: influx bucket-schema list + parent: influx bucket-schema +weight: 201 +related: + - /influxdb/cloud/organizations/buckets/bucket-schema +--- + +The `influx bucket-schema list` command lists the schemas of an +InfluxDB bucket that has the [`explicit` schema-type](/influxdb/cloud/reference/cli/influx/bucket/create/#create-a-bucket-with-an-explicit-schema). + +## Usage + +```sh +influx bucket-schema list [flags] +``` + +## Flags + +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:--------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| `-n` | `--bucket` | Bucket name (mutually exclusive with `--bucket-id`) | string | | +| `-i` | `--bucket-id` | Bucket ID (mutually exclusive with `--bucket`) | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-x` | `--extended-output` | Print column information for each measurement schema (default: false) | | | +| `-h` | `--help` | Help for the `create` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-n` | `--name` | Measurement name | string | | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +### List all schemas of a bucket and print column information + +```sh +influx bucket-schema list \ + --bucket example-bucket + --extended-output +``` + +### Print column details for a single measurement +```sh +influx bucket-schema list \ + --bucket example-bucket \ + --name cpu \ + --extended-output +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/bucket-schema/update.md b/content/influxdb/v2.1/reference/cli/influx/bucket-schema/update.md new file mode 100644 index 0000000000..bb56b36ca4 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/bucket-schema/update.md @@ -0,0 +1,96 @@ +--- +title: influx bucket-schema update +description: The `influx bucket-schema update` command updates the schema of an InfluxDB bucket that has the `explicit` schema-type. +menu: + influxdb_2_1_ref: + name: influx bucket-schema update + parent: influx bucket-schema +weight: 201 +related: + - /influxdb/cloud/organizations/buckets/bucket-schema +--- + +The `influx bucket-schema update` command updates the schema of an InfluxDB bucket that has the [`explicit` schema-type](/influxdb/cloud/reference/cli/influx/bucket/create/#create-a-bucket-with-an-explicit-schema). + +`bucket-schema update` requires a bucket with at least one defined schema. + +## Usage + +```sh +influx bucket-schema update [flags] +``` + +##### Supported operations +- Adding new columns to a schema + +##### Unsupported operations +- Modify existing columns in a schema +- Delete columns from a schema + +## Flags + +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:--------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| `-n` | `--bucket` | ({{< req >}}) Bucket name (mutually exclusive with `--bucket-id`) | string | | +| `-i` | `--bucket-id` | ({{< req >}}) Bucket ID (mutually exclusive with `--bucket`) | string | | +| | `--columns-file` | ({{< req >}}) Path to column definitions file. For more information, see [Create a columns file](/influxdb/cloud/reference/cli/influx/bucket-schema/create/#create-a-columns-file). | string | | +| | `--columns-format` | Columns file format (`csv`, `ndjson`, `json`, default: `auto`). For more information, see [Update a schema with columns format](#update-a-schema-with-columns-format) | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-x` | `--extended-output` | Print column information for each measurement schema (default: false) | | | +| `-h` | `--help` | Help for the `create` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-n` | `--name` | ({{< req >}}) Measurement name | string | | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +- [Update a schema using the influx CLI](#update-a-schema-using-the-influx-cli) +- [Update a schema and print column information](#update-a-schema-and-print-column-information) +- [Update a schema with columns format](#update-a-schema-specifying-the-columns-format) + +### Update a schema using the influx CLI + +```sh +influx bucket-schema update \ + --bucket example-bucket \ + --name temperature \ + --columns-file columns.csv +``` + +### Update a schema and print column information +```sh +influx bucket-schema update \ + --bucket example-bucket \ + --name cpu \ + --columns-file columns.csv \ + -extended-output +``` + +### Update a schema with columns format + +By default, InfluxDB attempts to detect the **columns file** format. +If your file's extension doesn't match the format, set the format with the `columns-format` flag. + +```sh +influx bucket-schema update \ + --bucket example-bucket \ + --name cpu \ + --columns-file columns.json \ + --columns-format ndjson +``` + +```sh +influx bucket-schema update \ + --bucket example-bucket \ + --name cpu \ + --columns-file columns.txt \ + --columns-format csv +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/bucket/_index.md b/content/influxdb/v2.1/reference/cli/influx/bucket/_index.md new file mode 100644 index 0000000000..9abb742921 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/bucket/_index.md @@ -0,0 +1,43 @@ +--- +title: influx bucket +description: The `influx bucket` command and its subcommands manage buckets in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx bucket + parent: influx +weight: 101 +influxdb/v2.1/tags: [buckets] +cascade: + related: + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +cascade: + metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +--- + +The `influx bucket` command and its subcommands manage buckets in InfluxDB. + +## Usage +``` +influx bucket [flags] +influx bucket [command] +``` + +## Subcommands +| Subcommand | Description | +|:---------- |:----------- | +| [create](/influxdb/v2.1/reference/cli/influx/bucket/create) | Create bucket | +| [delete](/influxdb/v2.1/reference/cli/influx/bucket/delete) | Delete bucket | +| [list](/influxdb/v2.1/reference/cli/influx/bucket/list) | List buckets | +| [update](/influxdb/v2.1/reference/cli/influx/bucket/update) | Update bucket | + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:-----------|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `bucket` command | | | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | diff --git a/content/influxdb/v2.1/reference/cli/influx/bucket/create.md b/content/influxdb/v2.1/reference/cli/influx/bucket/create.md new file mode 100644 index 0000000000..0228ba0d79 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/bucket/create.md @@ -0,0 +1,107 @@ +--- +title: influx bucket create +description: The `influx bucket create` command creates a bucket in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx bucket create + parent: influx bucket +weight: 201 +aliases: + - /influxdb/v2.1/reference/cli/influx/bucket/create/ +related: + - /influxdb/v2.1/organizations/buckets/create-bucket/ + - /influxdb/v2.1/reference/internals/shards/ + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +updated_in: CLI v2.1.0 +--- + +The `influx bucket create` command creates a bucket in InfluxDB. + +## Usage + +```sh +influx bucket create [flags] +``` + +## Flags + +| Flag | | Description | Input type | {{< cli/mapped >}} | +| :--- | :----------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------: | :-------------------- | +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-d` | `--description` | Bucket description | string | | +| `-h` | `--help` | Help for the `create` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-n` | `--name` | Bucket name | string | `INFLUX_BUCKET_NAME` | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| `-r` | `--retention` | Duration bucket retains data (0 is infinite, default is 0) | duration | | +| | `--schema-type` | Bucket schema type (`explicit`, default `implicit`) _(Cloud only)_. For more information, see [Manage bucket schema](/influxdb/cloud/organizations/buckets/bucket-schema/). | string | | +| | `--shard-group-duration` | Bucket shard group duration (OSS only) | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +{{% note %}} +Valid `--retention` units are nanoseconds (`ns`), microseconds (`us` or `µs`), +milliseconds (`ms`), seconds (`s`), minutes (`m`), hours (`h`), days (`d`), and weeks (`w`). +{{% /note %}} + +## Examples + +{{< cli/influx-creds-note >}} + +- [Create a bucket with infinite data retention](#create-a-bucket-with-infinite-data-retention) +- [Create a bucket that retains data for 30 days](#create-a-bucket-that-retains-data-for-30-days) +- [Create a bucket with a description](#create-a-bucket-with-a-description) +- [Create a bucket with a custom shard group duration](#create-a-bucket-with-a-custom-shard-group-duration) +- [Create a bucket with an explicit schema](#create-a-bucket-with-an-explicit-schema) + +##### Create a bucket with infinite data retention + +```sh +influx bucket create --name example-bucket +``` + +##### Create a bucket that retains data for 30 days + +```sh +influx bucket create \ + --name example-bucket \ + --retention 30d +``` + +##### Create a bucket with a description + +```sh +influx bucket create \ + --name example-bucket \ + --description "Example bucket description" +``` + +##### Create a bucket with a custom shard group duration + +Custom shard group durations are only supported in **InfluxDB OSS**. +The shard group duration must be shorter than the bucket's retention period. For more information, see [InfluxDB shards and shard groups](/influxdb/v2.1/reference/internals/shards/). + +```sh +influx bucket create \ + --name example-bucket \ + --retention 30d \ + --shard-group-duration 2d +``` + +##### Create a bucket with an explicit schema + +{{% cloud %}} +[Explicit bucket schemas](/influxdb/cloud/reference/cli/influx/bucket-schema) are only +supported in **InfluxDB Cloud**. +For more information, see [Manage bucket schema](/influxdb/cloud/organizations/buckets/bucket-schema/). +{{% /cloud %}} + +```sh +{{< get-shared-text "bucket-schema/bucket-schema-type.sh" >}} +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/bucket/delete.md b/content/influxdb/v2.1/reference/cli/influx/bucket/delete.md new file mode 100644 index 0000000000..e8d65d31fb --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/bucket/delete.md @@ -0,0 +1,53 @@ +--- +title: influx bucket delete +description: The `influx bucket delete` command deletes a bucket from InfluxDB and all the data it contains. +menu: + influxdb_2_1_ref: + name: influx bucket delete + parent: influx bucket +weight: 201 +aliases: + - /influxdb/v2.1/reference/cli/influx/bucket/delete/ +related: + - /influxdb/v2.1/organizations/buckets/delete-bucket/ + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +--- + +The `influx bucket delete` command deletes a bucket from InfluxDB and all the data it contains. + +## Usage +```sh +influx bucket delete [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `delete` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-i` | `--id` | Bucket ID _(required if no `--name`)_ | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-n` | `--name` | Bucket name _(requires `--org` or `org-id`)_ | string | | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Delete a bucket by name +```sh +influx bucket delete --name example-bucket +``` + +##### Delete a bucket by ID +```sh +influx bucket delete --id 06c86c40a9f36000 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/bucket/list.md b/content/influxdb/v2.1/reference/cli/influx/bucket/list.md new file mode 100644 index 0000000000..c58addb02b --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/bucket/list.md @@ -0,0 +1,66 @@ +--- +title: influx bucket list +description: The `influx bucket list` command lists and searches for buckets in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx bucket list + parent: influx bucket +weight: 201 +aliases: + - /influxdb/v2.1/reference/cli/influx/bucket/find + - /influxdb/v2.1/reference/cli/influx/bucket/list/ +updated_in: CLI v2.2.0 +--- + +The `influx bucket list` command lists and searches for buckets in InfluxDB. + +## Usage +``` +influx bucket list [flags] +``` + +#### Command aliases +`list`, `ls`, `find` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +| :--- | :---------------- | :--------------------------------------------------------------------------- | :--------: | :-------------------- | +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `list` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-i` | `--id` | Bucket ID | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| | `--limit` | Total number of buckets to fetch from the server, or 0 to return all buckets | string | | +| `-n` | `--name` | Bucket name | string | `INFLUX_BUCKET_NAME` | +| | `--offset` | Number of buckets to skip over in the list | | `INFLUX_ORG` | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--page-size` | Number of buckets to fetch per request to the server (default 20) | | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +- [List all buckets](#list-all-buckets) +- [List a bucket by name](#list-a-bucket-by-name) +- [List a bucket by ID](#list-a-bucket-by-id) + +##### List all buckets +```sh +influx bucket list +``` + +##### List a bucket by name +```sh +influx bucket list --name example-bucket +``` + +##### List a bucket by ID +```sh +influx bucket list --id 06c86c40a9f36000 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/bucket/update.md b/content/influxdb/v2.1/reference/cli/influx/bucket/update.md new file mode 100644 index 0000000000..836c68ca39 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/bucket/update.md @@ -0,0 +1,74 @@ +--- +title: influx bucket update +description: The `influx bucket update` command updates information associated with buckets in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx bucket update + parent: influx bucket +weight: 201 +aliases: + - /influxdb/v2.1/reference/cli/influx/bucket/update/ +related: + - /influxdb/v2.1/organizations/buckets/update-bucket/ + - /influxdb/v2.1/reference/internals/shards/ + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +--- + +The `influx bucket update` command updates information associated with buckets in InfluxDB. + +## Usage +``` +influx bucket update [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:-------------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-d` | `--description` | Bucket description | string | | +| `-h` | `--help` | Help for the `update` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-i` | `--id` | ({{< req >}}) Bucket ID | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-n` | `--name` | New bucket name | string | `INFLUX_BUCKET_NAME` | +| `-r` | `--retention` | New duration bucket will retain data | duration | | +| | `--shard-group-duration` | Custom shard group duration for the bucket (OSS only) | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +{{% note %}} +Valid `--retention` units are nanoseconds (`ns`), microseconds (`us` or `µs`), +milliseconds (`ms`), seconds (`s`), minutes (`m`), hours (`h`), days (`d`), and weeks (`w`). +{{% /note %}} + +## Examples + +{{< cli/influx-creds-note >}} + +##### Update the name of a bucket +```sh +influx bucket update \ + --id 06c86c40a9f36000 \ + --name new-bucket-name +``` + +##### Update the retention period of a bucket +```sh +influx bucket update \ + --id 06c86c40a9f36000 \ + --retention 90d +``` + +##### Update the shard group duration of a bucket +Custom shard group durations are only supported in **InfluxDB OSS**. +The shard group duration must be shorter than the buckets retention period. + +```sh +influx bucket update \ + --id 06c86c40a9f36000 \ + --shard-group-duration 2d +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/completion/_index.md b/content/influxdb/v2.1/reference/cli/influx/completion/_index.md new file mode 100644 index 0000000000..28d72552c2 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/completion/_index.md @@ -0,0 +1,61 @@ +--- +title: influx completion +description: > + The `influx completion` command outputs `influx` shell completion scripts for a + specified shell (`bash` or `zsh`). +menu: + influxdb_2_1_ref: + name: influx completion + parent: influx +weight: 101 +influxdb/v2.1/tags: [cli, tools] +related: + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +--- + +The `influx completion` command outputs `influx` shell completion scripts for a +specified shell (`bash` or `zsh`). + +## Usage +``` +influx completion [bash|zsh] [flags] +``` + +## Flags +| Flag | | Description | +|:---- |:--- |:----------- | +| `-h` | `--help` | Help for the `completion` command | + +## Install completion scripts + +Add the appropriate installation command below to your `.bashrc` or `.zshrc`. + +#### Completion snippets in .bashrc or .zshrc +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[bash](#) +[zsh](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +# macOS +$ source $(brew --prefix)/etc/bash_completion.d +$ source <(influx completion bash) + +# Ubuntu +$ source /etc/bash_completion.d +$ source <(influx completion bash) +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sh +# macOS +$ source <(influx completion zsh) + +# Ubuntu +$ source <(influx completion zsh) +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} diff --git a/content/influxdb/v2.1/reference/cli/influx/config/_index.md b/content/influxdb/v2.1/reference/cli/influx/config/_index.md new file mode 100644 index 0000000000..9c20246e23 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/config/_index.md @@ -0,0 +1,65 @@ +--- +title: influx config +description: The `influx config` command and subcommands manage multiple InfluxDB connection configurations. +menu: + influxdb_2_1_ref: + name: influx config + parent: influx +weight: 101 +influxdb/v2.1/tags: [config] +cascade: + related: + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +--- + +The `influx config` command displays the active InfluxDB connection configuration +and manages multiple connection configurations stored, by default, in `~/.influxdbv2/configs`. +Each connection includes a URL, token, associated organization, and active setting. +InfluxDB reads the token from the active connection configuration, so you don't +have to manually enter a token to log into InfluxDB. + +## Usage +``` +influx config [flags] +influx config [command] +influx config +``` + +##### Quickly switch between configurations +```sh +# Syntax +influx config + +# Example +influx config local-config +``` + +To quickly switch back to the previous configuration, use the following command: + +```sh +influx config - +``` + +## Examples +```sh +# Show the active connection configuration +influx config + +# Set a connection configuration as active +influx config local-config +``` + +## Subcommands +| Subcommand | Description | +|:---- |:----------- | +| [create](/influxdb/v2.1/reference/cli/influx/config/create) | Create a connection configuration | +| [list](/influxdb/v2.1/reference/cli/influx/config/create) | List connection configurations | +| [delete](/influxdb/v2.1/reference/cli/influx/config/rm) | Delete a connection configuration | +| [set](/influxdb/v2.1/reference/cli/influx/config/set) | Set or update a connection configuration | + +## Flags +| Flag | | Description | +|:---- |:--- |:----------- | +| `-h` | `--help` | Help for the `config` command | diff --git a/content/influxdb/v2.1/reference/cli/influx/config/create.md b/content/influxdb/v2.1/reference/cli/influx/config/create.md new file mode 100644 index 0000000000..8021fb517b --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/config/create.md @@ -0,0 +1,49 @@ +--- +title: influx config create +description: The `influx config create` command creates a InfluxDB connection configuration. +menu: + influxdb_2_1_ref: + name: influx config create + parent: influx config +weight: 201 +--- + +The `influx config create` command creates a InfluxDB connection configuration +and stores it in the `configs` file (by default, stored at `~/.influxdbv2/configs`). + +## Usage +``` +influx config create [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:-----------------|:-------------------------------------------------------------|:----------:|:----------------------| +| `-a` | `--active` | Set the specified connection to be the active configuration. | | | +| `-n` | `--config-name` | ({{< req >}}) Name of the new configuration. | string | | +| `-h` | `--help` | Help for the `create` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| `-u` | `--host-url` | ({{< req >}}) Connection URL for the new configuration. | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name | string | | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +##### Create a connection configuration and set it active +```sh +influx config create --active \ + -n config-name \ + -u http://localhost:8086 \ + -t mySuP3rS3cr3tT0keN \ + -o example-org +``` + +##### Create a connection configuration without setting it active +```sh +influx config create \ + -n config-name \ + -u http://localhost:8086 \ + -t mySuP3rS3cr3tT0keN \ + -o example-org +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/config/list.md b/content/influxdb/v2.1/reference/cli/influx/config/list.md new file mode 100644 index 0000000000..3e3014f7ef --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/config/list.md @@ -0,0 +1,29 @@ +--- +title: influx config list +description: The `influx config list` command lists all InfluxDB connection configurations. +menu: + influxdb_2_1_ref: + name: influx config list + parent: influx config +weight: 201 +--- + +The `influx config list` command lists all InfluxDB connection configurations in +the `configs` file (by default, stored at `~/.influxdbv2/configs`). +Each connection configuration includes a URL, API token, and active setting. +An asterisk (`*`) indicates the active configuration. + +## Usage +``` +influx config list [flags] +``` + +#### Command aliases +`list`, `ls` + +## Flags +| Flag | | Description | {{< cli/mapped >}} | +| :--- | :--------------- | :------------------------------------------- | :-------------------- | +| `-h` | `--help` | Help for the `list` command | | +| | `--hide-headers` | Hide table headers (default `false`) | `INFLUX_HIDE_HEADERS` | +| | `--json` | Output data as JSON (default `false`) | `INFLUX_OUTPUT_JSON` | diff --git a/content/influxdb/v2.1/reference/cli/influx/config/rm.md b/content/influxdb/v2.1/reference/cli/influx/config/rm.md new file mode 100644 index 0000000000..821139f6ac --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/config/rm.md @@ -0,0 +1,42 @@ +--- +title: influx config rm +description: The `influx config rm` command removes an InfluxDB connection configuration. +menu: + influxdb_2_1_ref: + name: influx config rm + parent: influx config +weight: 201 +aliases: + - /influxdb/v2.1/reference/cli/influx/config/delete/ +--- + +The `influx config rm` command removes an InfluxDB connection configuration +from the `configs` file (by default, stored at `~/.influxdbv2/configs`). + +## Usage +``` +influx config rm [flags] +``` + +#### Command aliases +`rm`, `remove`, `delete` + + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +| :--- | :--------------- | :------------------------------------------- | :--------: | :-------------------- | +| `-h` | `--help` | Help for the `delete` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | + +## Examples + +##### Delete a connection configuration +```sh +influx config rm local-config +``` + +##### Delete multiple connection configurations +```sh +influx config rm config-1 config-2 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/config/set.md b/content/influxdb/v2.1/reference/cli/influx/config/set.md new file mode 100644 index 0000000000..78640884c3 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/config/set.md @@ -0,0 +1,49 @@ +--- +title: influx config set +description: The `influx config set` command updates an InfluxDB connection configuration. +menu: + influxdb_2_1_ref: + name: influx config set + parent: influx config +weight: 201 +--- + +The `influx config set` command updates information in an InfluxDB connection +configuration in the `configs` file (by default, stored at `~/.influxdbv2/configs`). + +## Usage +``` +influx config set [flags] +``` + +#### Command aliases +`set` , `update` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +| :--- | :--------------- | :-------------------------------------------------------------- | :--------: | :-------------------- | +| `-a` | `--active` | Set the specified connection to active | | | +| `-n` | `--config-name` | Name for the InfluxDB connection configuration to set or update | string | | +| `-h` | `--help` | Help for the `set` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| `-u` | `--host-url` | URL for InfluxDB connection configuration to set or update | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name for the connection configuration | string | | + +## Examples + +##### Update a connection configuration and set it to active +```sh +influx config set --active \ + -n config-name \ + -t mySuP3rS3cr3tT0keN \ + -o example-org +``` + +##### Update a connection configuration and do not set it to active +```sh +influx config set \ + -n config-name \ + -t mySuP3rS3cr3tT0keN \ + -o example-org +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/dashboards/_index.md b/content/influxdb/v2.1/reference/cli/influx/dashboards/_index.md new file mode 100644 index 0000000000..aabaef27c2 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/dashboards/_index.md @@ -0,0 +1,54 @@ +--- +title: influx dashboards +description: > + The `influx dashboards` command lists existing InfluxDB dashboards. +menu: + influxdb_2_1_ref: + name: influx dashboards + parent: influx +weight: 101 +influxdb/v2.1/tags: [telegraf] +related: + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +--- + +The `influx dashboards` command lists existing InfluxDB dashboards. + +## Usage +```sh +influx dashboards [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:-----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `dashboards` command | | | +| | `--hide-headers` | Hide table headers | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `$INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-i` | `--id` | Dashboard ID to retrieve | stringArray | | +| | `--json` | Output data as JSON | | `INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### List all dashboards +```sh +influx dashboards +``` + +##### List only specific dashboards +```sh +influx dashboards \ + --id 068ad4a493f2d000 \ + --id 0623f2dabc000121 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/delete/_index.md b/content/influxdb/v2.1/reference/cli/influx/delete/_index.md new file mode 100644 index 0000000000..e3741c05a7 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/delete/_index.md @@ -0,0 +1,78 @@ +--- +title: influx delete +description: The `influx delete` command deletes points from an InfluxDB bucket. +menu: + influxdb_2_1_ref: + name: influx delete + parent: influx +weight: 101 +influxdb/v2.1/tags: [delete] +related: + - /influxdb/v2.1/write-data/delete-data + - /influxdb/v2.1/reference/syntax/delete-predicate + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.3+, InfluxDB 2.0.3+] +updated_in: CLI v2.2.0 +--- + +The `influx delete` command deletes [points](/influxdb/v2.1/reference/glossary/#point) +from an InfluxDB bucket in a specified time range. +Select points to delete within the specified time range using [delete predicate syntax](/influxdb/v2.1/reference/syntax/delete-predicate). + +{{% warn %}} +Running `influx delete` without the `-p` or `--predicate` flag deletes all data with timestamps between the specified +`--start` and `--stop` times in the specified bucket. +{{% /warn %}} + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| `-b` | `--bucket` | Name of bucket to remove data from (mutually exclusive with `--bucket-id`) | string | `INFLUX_BUCKET_NAME` | +| | `--bucket-id` | Bucket ID (mutually exclusive with `--bucket`) | string | `INFLUX_BUCKET_ID` | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `delete` command | | | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| `-p` | `--predicate` | InfluxQL-like predicate string (see [Delete predicate](/influxdb/v2.1/reference/syntax/delete-predicate)) | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| | `--start` | ({{< req >}}) Start time in RFC3339 format (i.e. `2009-01-02T23:00:00Z`) | string | | +| | `--stop` | ({{< req >}}) Stop time in RFC3339 format (i.e. `2009-01-02T23:00:00Z`) | string | | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +- [Delete all points in a measurement](#delete-all-points-in-a-measurement) +- [Delete points in a measurement with a specific tag value](#delete-points-in-a-measurement-with-a-specific-tag-value) +- [Delete all points within a specified time frame](#delete-all-points-within-a-specified-time-frame) + +##### Delete all points in a measurement +```sh +influx delete \ + --bucket example-bucket \ + --start 1970-01-01T00:00:00Z \ + --stop $(date +"%Y-%m-%dT%H:%M:%SZ") \ + --predicate '_measurement="example-measurement"' +``` + +##### Delete points in a measurement with a specific tag value +```sh +influx delete \ + --bucket example-bucket \ + --start 1970-01-01T00:00:00Z \ + --stop $(date +"%Y-%m-%dT%H:%M:%SZ") \ + --predicate '_measurement="example-measurement" AND host="old-host"' +``` + +##### Delete all points within a specified time frame +```sh +influx delete \ + --bucket example-bucket \ + --start 2020-03-01T00:00:00Z \ + --stop 2020-11-14T00:00:00Z +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/export/_index.md b/content/influxdb/v2.1/reference/cli/influx/export/_index.md new file mode 100644 index 0000000000..340330fee0 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/export/_index.md @@ -0,0 +1,111 @@ +--- +title: influx export +description: The `influx export` command exports existing resources as an InfluxDB template. +menu: + influxdb_2_1_ref: + parent: influx +weight: 101 +aliases: + - /influxdb/v2.1/reference/cli/influx/pkg/export/ +related: + - /influxdb/v2.1/influxdb-templates/create/ + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +cascade: + metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +--- + +The `influx export` command exports existing resources as an InfluxDB template. +_For detailed examples of exporting InfluxDB templates, see +[Create an InfluxDB template](/influxdb/v2.1/influxdb-templates/create/)._ + +## Usage + +``` +influx export [flags] +influx export [command] +``` + +## Available subcommands + +| Subcommand | Description | +|:---------- |:----------- | +| [all](/influxdb/v2.1/reference/cli/influx/export/all/) | Export all resources in an organization as a template | +| [stack](/influxdb/v2.1/reference/cli/influx/export/stack/) | Export all resources associated with a stack as a template | + +## Flags + +| Flag | | Description | Input Type | {{< cli/mapped >}} | +|:-----|:--------------------------|:---------------------------------------------------------------------------------|:-----------|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--bucket-names` | Comma-separated list of bucket names | string | | +| | `--buckets` | Comma-separated list of bucket IDs | string | | +| | `--check-names` | Comma-separated list of check names | string | | +| | `--checks` | Comma-separated list of check IDs | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| | `--dashboard-names` | Comma-separated list of dashboard names | string | | +| | `--dashboards` | Comma-separated list of dashboard IDs | string | | +| | `--endpoint-names` | Comma-separated list of notification endpoint names | string | | +| | `--endpoints` | Comma-separated list of notification endpoint IDs | string | | +| `-f` | `--file` | Template output file. Defaults to stdout. Use `.yml` or `.json` file extensions. | string | | +| `-h` | `--help` | Help for the `export` command | | | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:9999`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--label-names` | Comma-separated list of label names | string | | +| | `--labels` | Comma-separated list of label IDs | string | | +| | `--resource-type` | Resource type associated with all IDs via stdin | string | | +| | `--rule-names` | Comma-separated list of notification rule names | string | | +| | `--rules` | Comma-separated list of notification rule IDs | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| | `--stack-id` | Stack ID to include resources from in export | string | | +| | `--task-names` | Comma-separated list of task names | string | | +| | `--tasks` | Comma-separated list of task IDs | string | | +| | `--telegraf-config-names` | Comma-separated list of Telegraf configuration names | string | | +| | `--telegraf-configs` | Comma-separated list of Telegraf configuration IDs | string | | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | +| | `--variable-names` | Comma-separated list of variable names | string | | +| | `--variables` | Comma-separated list of variable IDs | string | | + +## Examples + +{{< cli/influx-creds-note >}} + +- [Export buckets by ID](#export-buckets-by-id) +- [Export buckets, labels, and dashboards by ID](#export-buckets-labels-and-dashboards-by-id) +- [Export buckets, labels, and dashboards by name](#export-buckets-labels-and-dashboards-by-name) +- [Export all resources associated with a stack](#export-all-resources-associated-with-a-stack) +- [Export resources both associated and not associated with a stack](#export-resources-both-associated-and-not-associated-with-a-stack) + +##### Export buckets by ID +```sh +influx export --buckets 0Xx0oox00XXoxxoo1,0Xx0oox00XXoxxoo2 +``` + +##### Export buckets, labels, and dashboards by ID +```sh +influx export \ + --buckets 0Xx0oox00XXoxxoo1,0Xx0oox00XXoxxoo2 \ + --labels o0x0oox0Xxoxx001,o0x0oox0Xxoxx002 \ + --dashboards 0XxXooXoo0xooXo0X1,0XxXooXoo0xooXo0X2 +``` + +##### Export buckets, labels, and dashboards by name +```sh +influx export \ + --bucket-names bucket1,bucket2,bucket3 \ + --label-names label1,label2,label3 \ + --dashboard-names dashboard1,dashboard2,dashboard3 +``` + +##### Export all resources associated with a stack +```sh +influx export --stack-id 0Xx0oox00XXoxxoo1 +``` + +##### Export resources both associated and not associated with a stack +```sh +influx export \ + --stack-id 0Xx0oox00XXoxxoo1 \ + --buckets o0x0oox0Xxoxx001,0XxXooXoo0xooXo0X2 \ + --dashboard-names bucket1 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/export/all.md b/content/influxdb/v2.1/reference/cli/influx/export/all.md new file mode 100644 index 0000000000..2b2adf346f --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/export/all.md @@ -0,0 +1,87 @@ +--- +title: influx export all +description: > + The `influx export all` command exports all resources in an organization as an InfluxDB template. +menu: + influxdb_2_1_ref: + parent: influx export +weight: 201 +aliases: + - /influxdb/v2.1/reference/cli/influx/pkg/export/all/ +related: + - /influxdb/v2.1/influxdb-templates/create/ + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +--- + +The `influx export all` command exports all resources in an +organization as an InfluxDB template. +_For detailed examples of exporting InfluxDB templates, see +[Create an InfluxDB template](/influxdb/v2.1/influxdb-templates/create/)._ + +{{% note %}} +To export resources as a template, you must use the **Operator token** created for +the initial InfluxDB user or an **All-Access token**. +For information about creating an All-Access API token, see [Create an API token](/influxdb/v2.1/security/tokens/create-token/). +{{% /note %}} + +## Usage +``` +influx export all [flags] +``` + +## Flags +| Flag | | Description | Input Type | {{< cli/mapped >}} | +|:-----|:------------------|:------------------------------------------------------------------------------------------------|:------------|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-f` | `--file` | Template output file. Defaults to stdout. Use `.yml` or `.json` file extensions. | string | | +| | `--filter` | Specify resources to export by labelName or resourceKind (format: `--filter=labelName=example`) | stringArray | | +| `-h` | `--help` | Help for the `export all` command | | | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-o` | `--org` | Organization name that owns the resources (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID that owns the resources (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + + +## Examples + +{{< cli/influx-creds-note >}} + +- [Export all resources in an organization as a template](#export-all-resources-in-an-organization-as-a-template) +- [Export all bucket resources as a template](#export-all-bucket-resources-as-a-template) +- [Export all resources associated with label Foo](#export-all-resources-associated-with-label-foo) +- [Export all bucket resources and with label Foo](#export-all-bucket-resources-with-label-foo) +- [Export all bucket or dashboard resources with label Foo](#export-all-bucket-or-dashboard-resources-with-label-foo) + +##### Export all resources in an organization as a template +```sh +influx export all +``` + +##### Export all bucket resources as a template +```sh +influx export all --filter=resourceKind=Bucket +``` + +##### Export all resources associated with label Foo +```sh +influx export all --filter=labelName=Foo +``` + +##### Export all bucket resources and with label Foo +```sh +influx export all \ + --filter=resourceKind=Bucket \ + --filter=labelName=Foo +``` + +##### Export all bucket or dashboard resources with label Foo +```sh +influx export all \ + --filter=resourceKind=Bucket \ + --filter=resourceKind=Dashboard \ + --filter=labelName=Foo +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/export/stack.md b/content/influxdb/v2.1/reference/cli/influx/export/stack.md new file mode 100644 index 0000000000..9e7ecd9625 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/export/stack.md @@ -0,0 +1,51 @@ +--- +title: influx export stack +description: > + The `influx export stack` command exports all resources associated with a stack as an InfluxDB template. +menu: + influxdb_2_1_ref: + parent: influx export +weight: 201 +aliases: + - /influxdb/v2.1/reference/cli/influx/pkg/export/stack +related: + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +--- + +The `influx export stack` command exports all resources associated with a stack as a template. +All `metadata.name` fields remain the same. + +{{% note %}} +To export resources as a template, you must use the **Operator token** created for +the initial InfluxDB user or an **All-Access token**. +For information about creating an All-Access API token, see [Create an API token](/influxdb/v2.1/security/tokens/create-token/). +{{% /note %}} + +## Usage +``` +influx export stack [flags] +``` + +## Flags +| Flag | | Description | Input Type | {{< cli/mapped >}} | +|:-----|:------------------|:---------------------------------------------------------------------------------|:-----------|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-f` | `--file` | Template output file. Defaults to stdout. Use `.yml` or `.json` file extensions. | string | | +| `-h` | `--help` | Help for the `export stack` command | | | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-o` | `--org` | Organization name that owns the resources (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID that owns the resources (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Export a stack as a template +```sh +influx export stack $STACK_ID +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/help/_index.md b/content/influxdb/v2.1/reference/cli/influx/help/_index.md new file mode 100644 index 0000000000..d88a039051 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/help/_index.md @@ -0,0 +1,25 @@ +--- +title: influx help +description: The `influx help` command provides help for any command in the `influx` command line interface. +menu: + influxdb_2_1_ref: + name: influx help + parent: influx +weight: 101 +related: + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +--- + +The `influx help` command provides help for any command in the `influx` command line interface. + +## Usage +``` +influx help [command] [flags] +``` + +## Flags +| Flag | | Description | +|:---- |:--- |:----------- | +| `-h` | `--help` | Help for the `help` command | diff --git a/content/influxdb/v2.1/reference/cli/influx/org/_index.md b/content/influxdb/v2.1/reference/cli/influx/org/_index.md new file mode 100644 index 0000000000..85346ed17e --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/org/_index.md @@ -0,0 +1,40 @@ +--- +title: influx org +description: The `influx org` command and its subcommands manage organization information in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx org + parent: influx +weight: 101 +influxdb/v2.1/tags: [organizations] +cascade: + related: + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +--- + +The `influx org` command and its subcommands manage organization information in InfluxDB. + +## Usage +``` +influx org [flags] +influx org [command] +``` + +#### Command aliases +`org`, `organization` + +## Subcommands +| Subcommand | Description | +|:---------- |:----------- | +| [create](/influxdb/v2.1/reference/cli/influx/org/create) | Create an organization | +| [delete](/influxdb/v2.1/reference/cli/influx/org/delete) | Delete an organization | +| [list](/influxdb/v2.1/reference/cli/influx/org/list) | List organizations | +| [members](/influxdb/v2.1/reference/cli/influx/org/members) | Organization membership commands | +| [update](/influxdb/v2.1/reference/cli/influx/org/update) | Update an organization | + +## Flags +| Flag | | Description | +|:---- |:--- |:----------- | +| `-h` | `--help` | Help for the `org` command | diff --git a/content/influxdb/v2.1/reference/cli/influx/org/create.md b/content/influxdb/v2.1/reference/cli/influx/org/create.md new file mode 100644 index 0000000000..2255092203 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/org/create.md @@ -0,0 +1,47 @@ +--- +title: influx org create +description: The `influx org create` creates an organization in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx org create + parent: influx org +weight: 201 +--- + +The `influx org create` creates an organization in InfluxDB. + +## Usage +``` +influx org create [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-d` | `--description` | Description of the organization | | | +| `-h` | `--help` | Help for the `create` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-n` | `--name` | ({{< req >}}) Organization name | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Create an organization +```sh +influx org create --name example-org +``` + +##### Create an organization with a description +```sh +influx org create \ + --name example-org \ + --description "Example organization description" +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/org/delete.md b/content/influxdb/v2.1/reference/cli/influx/org/delete.md new file mode 100644 index 0000000000..ff6f0916f8 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/org/delete.md @@ -0,0 +1,39 @@ +--- +title: influx org delete +description: The `influx org delete` command deletes an organization in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx org delete + parent: influx org +weight: 201 +--- + +The `influx org delete` command deletes an organization in InfluxDB. + +## Usage +``` +influx org delete [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `delete` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-i` | `--id` | ({{< req >}}) Organization ID | string | `INFLUX_ORG_ID` | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Delete an organization +```sh +influx org delete --id 0Xx0oox00XXoxxoo1 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/org/list.md b/content/influxdb/v2.1/reference/cli/influx/org/list.md new file mode 100644 index 0000000000..ecc173adec --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/org/list.md @@ -0,0 +1,59 @@ +--- +title: influx org list +description: The `influx org list` lists and searches for organizations in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx org list + parent: influx org +weight: 201 +aliases: + - /influxdb/v2.1/reference/influx/org/find +--- + +The `influx org list` lists and searches for organizations in InfluxDB. + +## Usage +``` +influx org list [flags] +``` + +#### Command aliases +`list`, `ls`, `find` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `list` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-i` | `--id` | Organization ID | string | `INFLUX_ORG` | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-n` | `--name` | Organization name | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +- [List all organizations](#list-all-organizations) +- [List a specific organization by name](#list-a-specific-organization-by-name) +- [List a specific organization by ID](#list-a-specific-organization-by-id) + +##### List all organizations +```sh +influx org list +``` + +##### List a specific organization by name +```sh +influx org list --name example-org +``` + +##### List a specific organization by ID +```sh +influx org list --id 0Xx0oox00XXoxxoo1 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/org/members/_index.md b/content/influxdb/v2.1/reference/cli/influx/org/members/_index.md new file mode 100644 index 0000000000..68e9f9ebcd --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/org/members/_index.md @@ -0,0 +1,30 @@ +--- +title: influx org members +description: The `influx org members` command and its subcommands manage organization members in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx org members + parent: influx org +weight: 201 +influxdb/v2.1/tags: [members, organizations] +--- + +The `influx org members` command and its subcommands manage organization members in InfluxDB. + +## Usage +``` +influx org members [flags] +influx org members [command] +``` + +## Subcommands +| Subcommand | Description | +|:---------- |:----------- | +| [add](/influxdb/v2.1/reference/cli/influx/org/members/add) | Add organization member | +| [list](/influxdb/v2.1/reference/cli/influx/org/members/list) | List organization members | +| [remove](/influxdb/v2.1/reference/cli/influx/org/members/remove) | Remove organization member | + +## Flags +| Flag | | Description | +|:---- |:--- |:----------- | +| `-h` | `--help` | Help for the `members` command | diff --git a/content/influxdb/v2.1/reference/cli/influx/org/members/add.md b/content/influxdb/v2.1/reference/cli/influx/org/members/add.md new file mode 100644 index 0000000000..9edfdebddf --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/org/members/add.md @@ -0,0 +1,38 @@ +--- +title: influx org members add +description: The `influx org members add` command adds a member to an organization in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx org members add + parent: influx org members +weight: 301 +--- + +The `influx org members add` command adds a member to an organization in InfluxDB. + +## Usage +``` +influx org members add [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:----------------|:-----------------------------------------------------------|:----------:|:---------------------| +| `-h` | `--help` | Help for the `add` command | | | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| `-i` | `--id` | Organization ID | string | `INFLUX_ORG_ID` | +| `-m` | `--member` | User ID | string | | +| `-n` | `--name` | Organization name | string | `INFLUX_ORG` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Add a member to an organization +```sh +influx org members add \ + --member 00x0oo0X0xxxo000 \ + --name example-org +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/org/members/list.md b/content/influxdb/v2.1/reference/cli/influx/org/members/list.md new file mode 100644 index 0000000000..daf578ae89 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/org/members/list.md @@ -0,0 +1,39 @@ +--- +title: influx org members list +description: The `influx org members list` command lists members within an organization in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx org members list + parent: influx org members +weight: 301 +--- + +The `influx org members list` command lists members within an organization in InfluxDB. + +## Usage +``` +influx org members list [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:-----------------|:-----------------------------------------------------------|:----------:|:----------------------| +| `-h` | `--help` | Help for the `list` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-i` | `--id` | Organization ID | string | `INFLUX_ORG_ID` | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-n` | `--name` | Organization name | string | `INFLUX_ORG` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### List members of an organization +```sh +influx org members list \ + --name example-org +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/org/members/remove.md b/content/influxdb/v2.1/reference/cli/influx/org/members/remove.md new file mode 100644 index 0000000000..adca6172fc --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/org/members/remove.md @@ -0,0 +1,39 @@ +--- +title: influx org members remove +description: The `influx org members remove` command removes a member from an organization in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx org members remove + parent: influx org members +weight: 301 +--- + +The `influx org members remove` command removes a member from an organization in InfluxDB. + +## Usage +``` +influx org members remove [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:----------------|:-----------------------------------------------------------|:----------:|:---------------------| +| `-h` | `--help` | Help for the `remove` command | | | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-i` | `--id` | Organization ID | string | `INFLUX_ORG_ID` | +| `-m` | `--member` | Member ID | string | | +| `-n` | `--name` | Organization name | string | `INFLUX_ORG` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Remove a member from an organization +```sh +influx org members remove \ + --member 00x0oo0X0xxxo000 \ + --name example-org +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/org/update.md b/content/influxdb/v2.1/reference/cli/influx/org/update.md new file mode 100644 index 0000000000..69be66c66d --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/org/update.md @@ -0,0 +1,50 @@ +--- +title: influx org update +description: The `influx org update` command updates information related to organizations in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx org update + parent: influx org +weight: 201 +--- + +The `influx org update` command updates information related to organizations in InfluxDB. + +## Usage +``` +influx org update [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:-------------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-d` | `--description` | New description for the organization | string | `INFLUX_ORG_DESCRIPTION` | +| `-h` | `--help` | Help for the `update` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-i` | `--id` | ({{< req >}}) Organization ID | string | `INFLUX_ORG_ID` | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-n` | `--name` | New organization name | string | `INFLUX_ORG` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Update the name of an organization +```sh +influx org update \ + --id 0Xx0oox00XXoxxoo1 + --name new-org-name +``` + +##### Update the description of an organization +```sh +influx org update \ + --id 0Xx0oox00XXoxxoo1 + --description "New example organization description" +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/ping/_index.md b/content/influxdb/v2.1/reference/cli/influx/ping/_index.md new file mode 100644 index 0000000000..c45f7d7839 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/ping/_index.md @@ -0,0 +1,35 @@ +--- +title: influx ping +description: > + The `influx ping` command checks the health of a running InfluxDB instance by + querying the `/health` endpoint. +menu: + influxdb_2_1_ref: + name: influx ping + parent: influx +weight: 101 +influxdb/v2.1/tags: [ping, health] +related: + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +--- + +The `influx ping` command checks the health of a running InfluxDB instance by +querying the `/health` endpoint. +It does not require an API token. + +## Usage +``` +influx ping [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:-----------|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `ping` command | | | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | diff --git a/content/influxdb/v2.1/reference/cli/influx/query/_index.md b/content/influxdb/v2.1/reference/cli/influx/query/_index.md new file mode 100644 index 0000000000..d5b4248f3a --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/query/_index.md @@ -0,0 +1,87 @@ +--- +title: influx query +description: > + The `influx query` command executes a literal Flux query provided as a string + or a literal Flux query contained in a file. +menu: + influxdb_2_1_ref: + name: influx query + parent: influx +weight: 101 +influxdb/v2.1/tags: [query] +related: + - /influxdb/v2.1/query-data/ + - /influxdb/v2.1/query-data/execute-queries/influx-query/ + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +updated_in: CLI v2.0.5 +--- + +The `influx query` command executes a literal Flux query provided as a string +or a literal Flux query contained in a file. + +## Usage +``` +influx query [query literal] [flags] +``` + +{{% note %}} +#### Remove unnecessary columns in large datasets +When using the `influx query` command to query and download large datasets, +drop columns such as `_start` and `_stop` to optimize the download file size. + +```js +// ... + |> drop(columns: ["_start", "_stop"]) +``` +{{% /note %}} + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-f` | `--file` | Path to Flux script file | string | | +| `-h` | `--help` | Help for the `query` command | | | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| `-p` | `--profilers` | Flux query profilers to enable (comma-separated) | string | | +| `-r` | `--raw` | Output raw query results (annotated CSV) | | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +- [Query InfluxDB with a Flux string](#query-influxdb-with-a-flux-string) +- [Query InfluxDB using a Flux file](#query-influxdb-with-a-flux-file) +- [Query InfluxDB and return annotated CSV](#query-influxdb-and-return-annotated-csv) +- [Query InfluxDB and append query profile data to results](#query-influxdb-and-append-query-profile-data-to-results) + +##### Query InfluxDB with a Flux string +```sh +influx query 'from(bucket:"example-bucket") |> range(start:-1m)' +``` + +##### Query InfluxDB with a Flux file +```sh +influx query --file /path/to/example-query.flux +``` + +##### Query InfluxDB and return annotated CSV +```sh +influx query 'from(bucket:"example-bucket") |> range(start:-1m)' --raw +``` + +##### Query InfluxDB and append query profile data to results +_For more information about profilers, see [Flux profilers](/{{< latest "flux" >}}/stdlib/profiler/#available-profilers)._ + +```sh +influx query \ + --profilers operator,query \ + 'from(bucket:"example-bucket") |> range(start:-1m)' +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/repl/_index.md b/content/influxdb/v2.1/reference/cli/influx/repl/_index.md new file mode 100644 index 0000000000..a94adf68d9 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/repl/_index.md @@ -0,0 +1,44 @@ +--- +title: influx repl +description: > + The `influx repl` command opens an interactive Read-Eval-Print Loop (REPL) + from which you can run Flux commands. +influxdb/v2.1/tags: [query] +related: + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +--- + +{{% warn %}} +#### Removed in InfluxDB 2.0 beta-16 +The `influx repl` command was removed in **InfluxDB 2.0 beta-16**. +To use the Flux REPL, build the REPL from source. +For more information, see the [Flux GitHub repository](https://github.com/influxdata/flux/#readme). +{{% /warn %}} + +The `influx repl` command opens an interactive Read-Eval-Print Loop (REPL) +from which you can run Flux commands. + +## Usage +``` +influx repl [flags] +``` + +{{% note %}} +Use **ctrl + d** to exit the REPL. +{{% /note %}} + +To use the Flux REPL, you must first authenticate with a [token](/influxdb/v2.1/security/tokens/view-tokens/). + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `repl` command | | | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | diff --git a/content/influxdb/v2.1/reference/cli/influx/restore/index.md b/content/influxdb/v2.1/reference/cli/influx/restore/index.md new file mode 100644 index 0000000000..42921756cc --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/restore/index.md @@ -0,0 +1,95 @@ +--- +title: influx restore +description: The `influx restore` command restores backup data and metadata from an InfluxDB backup directory. +influxdb/v2.1/tags: [restore] +menu: + influxdb_2_1_ref: + parent: influx +weight: 101 +alias: + - /influxdb/v2.1/reference/cli/influxd/restore/ +related: + - /influxdb/v2.1/backup-restore/restore/ + - /influxdb/v2.1/reference/cli/influx/backup/ + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +updated_in: CLI v2.0.7 +--- + +The `influx restore` command restores backup data and metadata from an InfluxDB OSS backup directory. + +### The restore process +When restoring data from a backup file set, InfluxDB temporarily moves existing +data and metadata while `restore` runs. +After `restore` completes, the temporary data is deleted. +If the restore process fails, InfluxDB preserves the data in the temporary location. + +_For information about recovering from a failed restore process, see +[Restore data](/influxdb/v2.1/backup-restore/restore/#recover-from-a-failed-restore)._ + +{{% note %}} +#### Cannot restore to existing buckets +The `influx restore` command cannot restore data to existing buckets. +Use the `--new-bucket` flag to create a bucket with a new name and restore data into it. +To restore data and retain bucket names, [delete existing buckets](/influxdb/v2.1/organizations/buckets/delete-bucket/) +and then begin the restore process. +{{% /note %}} + +## Usage + +``` +influx restore [flags] +``` + +## Flags + +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| `-b` | `--bucket` | Name of the bucket to restore (mutually exclusive with `--bucket-id`) | string | | +| | `--bucket-id` | ID of the bucket to restore (mutually exclusive with `--bucket`) | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| | `--full` | Fully restore and replace all data on server | | | +| `-h` | `--help` | Help for the `restore` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| | `--new-bucket` | Name of the bucket to restore to | string | | +| | `--new-org` | Name of the organization to restore to | string | | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +- [Restore backup data](#restore-backup-data) +- [Restore backup data for a specific bucket into a new bucket](#restore-backup-data-for-a-specific-bucket-into-a-new-bucket) +- [Restore and replace all data](#restore-and-replace-all-data) + +##### Restore backup data +```sh +influx restore /path/to/backup/dir/ +``` + +##### Restore backup data for a specific bucket into a new bucket +```sh +influx restore \ + --bucket example-bucket \ + --new-bucket new-example-bucket \ + /path/to/backup/dir/ +``` + +##### Restore and replace all data +{{% note %}} +`influx restore --full` restores all time series data _and_ InfluxDB key-value +data such as tokens, dashboards, users, etc. +{{% /note %}} + +```sh +influx restore --full /path/to/backup/dir/ +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/secret/_index.md b/content/influxdb/v2.1/reference/cli/influx/secret/_index.md new file mode 100644 index 0000000000..1004013cf5 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/secret/_index.md @@ -0,0 +1,36 @@ +--- +title: influx secret +description: The `influx secret` command manages secrets. +menu: + influxdb_2_1_ref: + name: influx secret + parent: influx +weight: 101 +influxdb/v2.1/tags: [secrets] +cascade: + related: + - /influxdb/v2.1/security/secrets/ + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +--- + +The `influx secret` command manages [secrets](/influxdb/v2.1/reference/glossary/#secret). + +## Usage +``` +influx secret [flags] +influx secret [subcommand] +``` + +## Subcommands +| Subcommand | Description | +|:---------- |:----------- | +| [delete](/influxdb/v2.1/reference/cli/influx/secret/delete/) | Delete a secret | +| [list](/influxdb/v2.1/reference/cli/influx/secret/list/) | List secrets | +| [update](/influxdb/v2.1/reference/cli/influx/secret/update/) | Add or update a secret | + +## Flags +| Flag | | Description | +|:---- |:--- |:----------- | +| `-h` | `--help` | Help for the `secret` command | diff --git a/content/influxdb/v2.1/reference/cli/influx/secret/delete.md b/content/influxdb/v2.1/reference/cli/influx/secret/delete.md new file mode 100644 index 0000000000..1b806bf496 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/secret/delete.md @@ -0,0 +1,42 @@ +--- +title: influx secret delete +description: The `influx secret delete` command deletes secrets. +menu: + influxdb_2_1_ref: + name: influx secret delete + parent: influx secret +weight: 101 +influxdb/v2.1/tags: [secrets] +--- + +The `influx secret delete` command deletes secrets. + +## Usage +``` +influx secret delete [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `delete` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-k` | `--key` | ({{< req >}}) Secret key | string | | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Delete a secret +```sh +influx secret delete --key EXAMPLE_SECRET_KEY +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/secret/list.md b/content/influxdb/v2.1/reference/cli/influx/secret/list.md new file mode 100644 index 0000000000..9382211e72 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/secret/list.md @@ -0,0 +1,44 @@ +--- +title: influx secret list +description: The `influx secret list` command lists secret keys. +menu: + influxdb_2_1_ref: + name: influx secret list + parent: influx secret +weight: 101 +influxdb/v2.1/tags: [secrets] +--- + +The `influx secret list` command lists secret keys. + +## Usage +``` +influx secret list [flags] +``` + +#### Command aliases +`list`, `ls`, `find` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `list` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### List all secret keys +```sh +influx secret list +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/secret/update.md b/content/influxdb/v2.1/reference/cli/influx/secret/update.md new file mode 100644 index 0000000000..d19b1aa934 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/secret/update.md @@ -0,0 +1,61 @@ +--- +title: influx secret update +description: The `influx secret update` command adds and updates secrets. +menu: + influxdb_2_1_ref: + name: influx secret update + parent: influx secret +weight: 101 +influxdb/v2.1/tags: [secrets] +--- + +The `influx secret update` command adds and updates secrets. +Provide the secret key with the `-k` or `--key` flag. +You may also provide the secret value with the `-v` or `--value` flag. +If you do not provide the secret value with the `-v` or `--value` flag, +enter the value when prompted. + +{{% warn %}} +Providing a secret value with the `-v` or `--value` flag may expose the secret +in your command history. +{{% /warn %}} + +## Usage +``` +influx secret update [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `update` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-k` | `--key` | ({{< req >}}) Secret key | string | | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | +| `-v` | `--value` | ({{< req >}}) Secret value | string | | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Add a secret +```sh +influx secret update \ + --key EXAMPLE_KEY \ + --value EXAMPLE_VALUE +``` + +##### Update an existing secret +```sh +influx secret update \ + --key EXAMPLE_KEY \ + --value NEW_EXAMPLE_VALUE +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/setup/_index.md b/content/influxdb/v2.1/reference/cli/influx/setup/_index.md new file mode 100644 index 0000000000..6cbeb725b9 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/setup/_index.md @@ -0,0 +1,70 @@ +--- +title: influx setup +description: > + The `influx setup` command walks through the initial InfluxDB OSS setup process, + creating a default user, organization, and bucket. +menu: + influxdb_2_1_ref: + name: influx setup + parent: influx +weight: 101 +influxdb/v2.1/tags: [get-started] +related: + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +updated_in: CLI v2.0.3 +canonical: /{{< latest "influxdb" "v2" >}}/reference/cli/influx/setup/ +--- + +The `influx setup` command walks through the initial InfluxDB OSS setup process, +creating a default user, organization, and bucket. + +{{% note %}} +The **Operator token** created in the InfluxDB setup process has full read and write +access to all organizations in the database. +{{% /note %}} + +## Usage +``` +influx setup [flags] +``` + +## Flags +| Flag | | Description | Data type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:---------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| `-b` | `--bucket` | Primary bucket name | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-f` | `--force` | Skip confirmation prompt | | | +| `-h` | `--help` | Help for the `setup` command | | | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-o` | `--org` | Primary organization name | string | | +| `-p` | `--password` | Password for primary user | string | | +| `-r` | `--retention` | Duration bucket will retain data (0 is infinite, default is 0) | duration | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | Token for admin user (auto-generated by default) | string | `INFLUX_TOKEN` | +| `-u` | `--username` | Primary username | string | | + +{{% note %}} +Valid `--retention` units are nanoseconds (`ns`), microseconds (`us` or `µs`), +milliseconds (`ms`), seconds (`s`), minutes (`m`), hours (`h`), days (`d`), and weeks (`w`). +{{% /note %}} + +## Examples + +##### Start interactive InfluxDB setup +```sh +influx setup +``` + +##### Set up InfluxDB with all required information and skip confirmation +```sh +influx setup \ + --org example-org \ + --bucket example-bucket \ + --username example-user \ + --password ExAmPl3PA55W0rD \ + --force +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/stacks/_index.md b/content/influxdb/v2.1/reference/cli/influx/stacks/_index.md new file mode 100644 index 0000000000..1be3cd91b6 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/stacks/_index.md @@ -0,0 +1,79 @@ +--- +title: influx stacks +description: > + The `influx stacks` command and its subcommands list and manage InfluxDB stacks + and associated resources. +menu: + influxdb_2_1_ref: + name: influx stacks + parent: influx +weight: 101 +aliases: + - /influxdb/v2.1/reference/cli/influx/pkg/stack/list/ +influxdb/v2.1/tags: [templates] +cascade: + related: + - /influxdb/v2.1/influxdb-templates/stacks/ + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.1+, InfluxDB 2.0.1+] +--- + +The `influx stacks` command and its subcommands list and manage InfluxDB stacks +and associated resources. + +## Usage +``` +influx stacks [flags] +influx stacks [command] +``` + +## Subcommands +| Subcommand | Description | +|:------- |:----------- | +| [init](/influxdb/v2.1/reference/cli/influx/stacks/init/) | Initialize a stack | +| [remove](/influxdb/v2.1/reference/cli/influx/stacks/remove/) | Remove a stack | + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:-----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `stacks` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| | `--stack-id` | Stack IDs to filter by | stringArray | | +| | `--stack-name` | Stack names to filter by | stringArray | | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +- [List all stacks](#list-all-stacks) +- [Filter stacks by name](#filter-stacks-by-name) +- [Filter stacks by ID](#filter-stacks-by-id) + +##### List all stacks +```sh +influx stacks +``` + +##### Filter stacks by name +```sh +influx stacks \ + --stack-name stack1 \ + --stack-name stack2 +``` + +##### Filter stacks by ID +```sh +influx stacks \ + --stack-id 0Xx0oox00XXoxxoo1 \ + --stack-id 0Xx0oox00XXoxxoo2 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/stacks/init.md b/content/influxdb/v2.1/reference/cli/influx/stacks/init.md new file mode 100644 index 0000000000..c980020ac5 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/stacks/init.md @@ -0,0 +1,53 @@ +--- +title: influx stacks init +description: The `influx stacks init` command initializes an InfluxDB stack. +menu: + influxdb_2_1_ref: + name: influx stacks init + parent: influx stacks +weight: 201 +aliases: + - /influxdb/v2.1/reference/cli/influx/pkg/stack/init/ +influxdb/v2.1/tags: [templates] +--- + +The `influx stacks init` command initializes an InfluxDB stack. + +## Usage +``` +influx stacks init [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:----------------------|:----------------------------------------------------------------------|:---------------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `init` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-d` | `--stack-description` | Stack description | string | | +| `-n` | `--stack-name` | Stack name | string | | +| `-u` | `--template-url` | Template URLs to associate with a stack | list of strings | | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Initialize a stack with a name and description + +```sh +influx stack init -n "Example Stack" -d "InfluxDB stack for monitoring some awesome stuff" +``` + +##### Initialize a stack with a name and URLs to associate with the stack + +```sh +influx stack init -n "Example Stack" -u https://example.com/template-1.yml +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/stacks/remove.md b/content/influxdb/v2.1/reference/cli/influx/stacks/remove.md new file mode 100644 index 0000000000..3ec1f7cf7d --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/stacks/remove.md @@ -0,0 +1,48 @@ +--- +title: influx stacks remove +description: The `influx stacks remove` command removes an InfluxDB stack and all associated resources. +menu: + influxdb_2_1_ref: + name: influx stacks remove + parent: influx stacks +weight: 201 +aliases: + - /influxdb/v2.1/reference/cli/influx/pkg/stack/remove/ +influxdb/v2.1/tags: [templates] +--- + +The `influx stacks remove` command removes an InfluxDB stack and all associated resources. + +## Usage +``` +influx stacks remove [flags] +``` + +#### Command aliases +`remove`, `rm`, `uninstall` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:---------------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| | `--force` | Skip confirmation prompt. | | | +| `-h` | `--help` | Help for the `remove` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| | `--stack-id` | Stack IDs to remove | list of strings | | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Remove a stack and all of its associated resources +```sh +influx stacks remove --stack-id 0Xx0oox00XXoxxoo1 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/stacks/update.md b/content/influxdb/v2.1/reference/cli/influx/stacks/update.md new file mode 100644 index 0000000000..c435a59163 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/stacks/update.md @@ -0,0 +1,89 @@ +--- +title: influx stacks update +description: The 'influx stacks update' command updates an InfluxDB stack. +menu: + influxdb_2_1_ref: + name: influx stacks update + parent: influx stacks +weight: 201 +influxdb/v2.1/tags: [templates] +updated_in: CLI v2.0.4 +--- + +The `influx stacks update` command updates an InfluxDB stack. + +## Usage +``` +influx stacks update [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:----------------------|:----------------------------------------------------------------------|:---------------:|:----------------------| +| | `--addResource` | Associate an existing resource with a stack | string | | +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-f` | `--export-file` | Destination for exported template | string | | +| `-h` | `--help` | Help for the `update` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-i` | `--stack-id` | The stack ID to update | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-d` | `--stack-description` | Stack description | string | | +| `-n` | `--stack-name` | Stack name | string | | +| `-u` | `--template-url` | Template URLs to associate with a stack | list of strings | | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +{{% warn %}} +#### Export an updated template +To prevent accidental changes, we **strongly recommend** exporting a new template +any time you add additional resources to a stack using the `--addResource` flag +with the `influx stack update` command. +The updated stack will differ from the previous template. +If you apply the outdated template, InfluxDB will revert the updates and remove +the added resources. +{{% /warn %}} + +## Examples + +{{< cli/influx-creds-note >}} + +- [Update a stack with a name and description](#update-a-stack-with-a-name-and-description) +- [Update a stack with a name and urls to associate with stack](#update-a-stack-with-a-name-and-urls-to-associate-with-stack) +- [Update a stack with new resources to manage](#update-a-stack-with-new-resources-to-manage) +- [Update a stack with new resources and export the stack as a template](#update-a-stack-with-new-resources-and-export-the-stack-as-a-template) + +##### Update a stack with a name and description +```sh +influx stack update \ + -i ab12cd34ef56 \ + -n "New stack name" \ + -d "New stack description" +``` + +##### Update a stack with a name and URLs to associate with stack +```sh +influx stack update \ + -i ab12cd34ef56 \ + -n "New stack name" \ + --template-url https://example.com/template-1.yml \ + --template-url https://example.com/template-2.yml +``` + +##### Update a stack with new resources to manage +```sh +influx stacks update \ + --stack-id ab12cd34ef56 \ + --addResource=Bucket=12ab34cd56ef \ + --addResource=Dashboard=98zy76xw54vu +``` + +##### Update a stack with new resources and export the stack as a template +```sh +influx stacks update \ + --stack-id ab12cd34ef56 \ + --addResource=Bucket=12ab34cd56ef \ + --export-file /path/to/template-file.yml +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/task/_index.md b/content/influxdb/v2.1/reference/cli/influx/task/_index.md new file mode 100644 index 0000000000..be502fa498 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/task/_index.md @@ -0,0 +1,40 @@ +--- +title: influx task +description: The `influx task` command and its subcommands manage tasks in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx task + parent: influx +weight: 101 +influxdb/v2.1/tags: [tasks] +cascade: + related: + - /influxdb/v2.1/process-data/ + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +--- + +The `influx task` command and its subcommands manage tasks in InfluxDB. + +### Usage +``` +influx task [flags] +influx task [command] +``` + +### Subcommands +| Subcommand | Description | +|:---------- |:----------- | +| [create](/influxdb/v2.1/reference/cli/influx/task/create) | Create task | +| [delete](/influxdb/v2.1/reference/cli/influx/task/delete) | Delete task | +| [list](/influxdb/v2.1/reference/cli/influx/task/list) | List tasks | +| [log](/influxdb/v2.1/reference/cli/influx/task/log) | Log related commands | +| [retry-failed](/influxdb/v2.1/reference/cli/influx/task/retry-failed) | Retry failed task runs | +| [run](/influxdb/v2.1/reference/cli/influx/task/run) | Run related commands | +| [update](/influxdb/v2.1/reference/cli/influx/task/update) | Update task | + +### Flags +| Flag | | Description | +|:---- |:--- |:----------- | +| `-h` | `--help` | Help for the `task` command | diff --git a/content/influxdb/v2.1/reference/cli/influx/task/create.md b/content/influxdb/v2.1/reference/cli/influx/task/create.md new file mode 100644 index 0000000000..3d1e9bdacd --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/task/create.md @@ -0,0 +1,59 @@ +--- +title: influx task create +description: The `influx task create` command creates a task in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx task create + parent: influx task +weight: 201 +--- + +The `influx task create` command creates a task in InfluxDB. + +## Usage +``` +influx task create [task literal] [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-f` | `--file` | Path to Flux script file | string | | +| `-h` | `--help` | Help for the `create` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Example + +{{< cli/influx-creds-note >}} + +##### Create a task using raw Flux +```sh +export FLUX_TASK=' + option task = { + name: "Example Task", + every: 1d + } + + from(bucket: "example-bucket") + |> range(start: -task.every) + |> filter(fn: (r) => (r._measurement == "m") + |> aggregateWindow(every: 1h, fn: mean) + |> to(bucket: "default-ds-1d", org: "my-org") +' + +influx task create $FLUX_TASK +``` + +##### Create a task from a file +```sh +influx task create --file /path/to/example-task.flux +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/task/delete.md b/content/influxdb/v2.1/reference/cli/influx/task/delete.md new file mode 100644 index 0000000000..66f2177ea8 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/task/delete.md @@ -0,0 +1,41 @@ +--- +title: influx task delete +description: The `influx task delete` command deletes a task in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx task delete + parent: influx task +weight: 201 +--- + +The `influx task delete` command deletes a task in InfluxDB. + +## Usage +``` +influx task delete [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `delete` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-i` | `--id` | ({{< req >}}) Task ID | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Delete a task +```sh +influx task delete --id 0Xx0oox00XXoxxoo1 +``` + + diff --git a/content/influxdb/v2.1/reference/cli/influx/task/list.md b/content/influxdb/v2.1/reference/cli/influx/task/list.md new file mode 100644 index 0000000000..fa305b563d --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/task/list.md @@ -0,0 +1,68 @@ +--- +title: influx task list +description: The `influx task list` command lists and searches for tasks in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx task list + parent: influx task +weight: 201 +aliases: + - /influxdb/v2.1/reference/cli/influx/task/find +--- + +The `influx task list` command lists and searches for tasks in InfluxDB. + +## Usage +``` +influx task list [flags] +``` + +#### Command aliases +`list`, `ls`, `find` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `list` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-i` | `--id` | Task ID | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| | `--limit` | Number of tasks to find (default `100`) | integer | | +| `-o` | `--org` | Task organization name | string | `INFLUX_ORG` | +| | `--org-id` | Task organization ID | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | +| `-n` | `--user-id` | Task owner ID | string | | + +## Examples + +{{< cli/influx-creds-note >}} + +- [List all tasks](#list-all-tasks) +- [List a specific task](#list-a-specific-task) +- [Limit the number of tasks returned to 20](#limit-the-number-of-tasks-returned-to-20) +- [List all tasks created by a specific user](#list-all-tasks-created-by-a-specific-user) + +##### List all tasks +```sh +influx task list +``` + +##### List a specific task +```sh +influx task list --id 0Xx0oox00XXoxxoo1 +``` + +##### Limit the number of tasks returned to 20 +```sh +influx task list --limit 20 +``` + +##### List all tasks created by a specific user +```sh +influx task list --user-id 0Xx0oox00XXoxxoo1 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/task/log/_index.md b/content/influxdb/v2.1/reference/cli/influx/task/log/_index.md new file mode 100644 index 0000000000..23d3c37e4f --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/task/log/_index.md @@ -0,0 +1,30 @@ +--- +title: influx task log +description: > + The `influx task log` and its subcommand, `list`, output log information + related to a task. +menu: + influxdb_2_1_ref: + name: influx task log + parent: influx task +weight: 201 +influxdb/v2.1/tags: [logs] +--- + +The `influx task log` command and its subcommand `list` output log information related to a task. + +## Usage +``` +influx task log [flags] +influx task log [command] +``` + +## Subcommands +| Subcommand | Description | +|:---------- |:----------- | +| [list](/influxdb/v2.1/reference/cli/influx/task/log/list) | List logs for task | + +## Flags +| Flag | | Description | +|:---- |:--- |:----------- | +| `-h` | `--help` | Help for the `log` command | diff --git a/content/influxdb/v2.1/reference/cli/influx/task/log/list.md b/content/influxdb/v2.1/reference/cli/influx/task/log/list.md new file mode 100644 index 0000000000..eb7469c59b --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/task/log/list.md @@ -0,0 +1,52 @@ +--- +title: influx task log list +description: The `influx task log list` command outputs log information related to a task. +menu: + influxdb_2_1_ref: + name: influx task log list + parent: influx task log +weight: 301 +aliases: + - /influxdb/v2.1/reference/cli/influx/task/log/list +--- + +The `influx task log list` command outputs log information related to a task. + +## Usage +``` +influx task log list [flags] +``` + +#### Command aliases +`list`, `ls`, `find` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `list` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--run-id` | Run ID | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| | `--task-id` | ({{< req >}}) Task ID | string | | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### List logs from all task executions +```sh +influx task log list --task-id 0Xx0oox00XXoxxoo1 +``` + +##### List logs from a specific task execution +```sh +influx task log list \ + --task-id 0Xx0oox00XXoxxoo1 \ + --run-id ox0Xx0ooxx00XXoo2 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/task/retry-failed.md b/content/influxdb/v2.1/reference/cli/influx/task/retry-failed.md new file mode 100644 index 0000000000..94d1e76b58 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/task/retry-failed.md @@ -0,0 +1,98 @@ +--- +title: influx task retry-failed +description: The `influx task retry-failed` command retries failed InfluxDB task runs. +menu: + influxdb_2_1_ref: + name: influx task retry-failed + parent: influx task +weight: 201 +metadata: [influx CLI 2.0.5+, InfluxDB 2.0.5+] +--- + +The `influx task retry-failed` command retries failed InfluxDB task runs. +## Usage +``` +influx task retry-failed [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:--------------------------------------------------------------------------|:----------:|:----------------------| +| | `--after` | Retry task runs that occurred after this time (RFC3339 timestamp) | string | | +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| | `--before` | Retry task runs that occurred before this time (RFC3339 timestamp) | string | | +| | `--dry-run` | Print information about task runs that would be retried | | | +| `-h` | `--help` | Help for the `list` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-i` | `--id` | Task ID | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Task organization name | string | `INFLUX_ORG` | +| | `--org-id` | Task organization ID | string | `INFLUX_ORG_ID` | +| | `--run-limit` | Maximum number of failed runs to retry per task (`1-500`, default `100`) | integer | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| | `--task-limit` | Maximum number of tasks to retry failed runs for (`1-500`, default `100`) | integer | | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +{{% note %}} +#### Required permissions +Use an [{{% oss-only %}}**Operator** or{{% /oss-only %}} **All-Access** token](/influxdb/v2.1/security/tokens/) to retry failed tasks. +{{% /note %}} + +- [Retry failed task runs for a specific task ID](#retry-failed-task-runs-for-a-specific-task-id) +- [Retry failed task runs that occurred before a specific time](#retry-failed-task-runs-that-occurred-before-a-specific-time) +- [Retry failed task runs that occurred after a specific time](#retry-failed-task-runs-that-occurred-after-a-specific-time) +- [Retry failed task runs that occurred in a specific time range](#retry-failed-task-runs-that-occurred-in-a-specific-time-range) +- [Retry failed runs for a limited number of tasks](#retry-failed-runs-for-a-limited-number-of-tasks) +- [Retry a limited number of failed runs for a task](#retry-a-limited-number-of-failed-runs-for-a-task) +- [Print information about runs that will be retried](#print-information-about-runs-that-will-be-retried) + +##### Retry failed task runs for a specific task ID +```sh +influx task retry-failed \ + --id 0Xx0oox00XXoxxoo1 +``` + +##### Retry failed task runs that occurred before a specific time +```sh +influx task retry-failed \ + --before 2021-01-01T00:00:00Z +``` + +##### Retry failed task runs that occurred after a specific time +```sh +influx task retry-failed \ + --after 2021-01-01T00:00:00Z +``` + +##### Retry failed task runs that occurred in a specific time range +```sh +influx task retry-failed \ + --after 2021-01-01T00:00:00Z \ + --before 2021-01-01T23:59:59Z +``` + +##### Retry failed runs for a limited number of tasks +```sh +influx task retry-failed \ + --task-limit 5 +``` + +##### Retry a limited number of failed runs for a task +```sh +influx task retry-failed \ + --id 0Xx0oox00XXoxxoo1 \ + --run-limit 5 +``` + +##### Print information about runs that will be retried +```sh +influx task retry-failed \ + --dry-run +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/task/run/_index.md b/content/influxdb/v2.1/reference/cli/influx/task/run/_index.md new file mode 100644 index 0000000000..9a3d372558 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/task/run/_index.md @@ -0,0 +1,30 @@ +--- +title: influx task run +description: > + The `influx task run` command and its subcommand, `list` output information + related to runs of a task. +menu: + influxdb_2_1_ref: + name: influx task run + parent: influx task +weight: 201 +--- + +The `influx task run` command and its subcommand `list` output information related to runs of a task. + +## Usage +``` +influx task run [flags] +influx task run [command] +``` + +## Subcommands +| Subcommand | Description | +|:---------- |:----------- | +| [list](/influxdb/v2.1/reference/cli/influx/task/run/list) | List runs for a task | +| [retry](/influxdb/v2.1/reference/cli/influx/task/run/retry) | Retry a task | + +## Flags +| Flag | | Description | +|:---- |:--- |:----------- | +| `-h` | `--help` | Help for the `run` command | diff --git a/content/influxdb/v2.1/reference/cli/influx/task/run/list.md b/content/influxdb/v2.1/reference/cli/influx/task/run/list.md new file mode 100644 index 0000000000..3eab46a00c --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/task/run/list.md @@ -0,0 +1,66 @@ +--- +title: influx task run list +description: The `influx task run list` command outputs information related to runs of a task. +menu: + influxdb_2_1_ref: + name: influx task run list + parent: influx task run +weight: 301 +aliases: + - /influxdb/v2.1/reference/cli/influx/task/run/find +--- + +The `influx task run list` command outputs information related to runs of a task. + +## Usage +``` +influx task run list [flags] +``` + +#### Command aliases +`list`, `ls`, `find` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--after` | After-time for filtering | string | | +| | `--before` | Before-time for filtering | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `list` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| | `--limit` | Limit the number of results | integer | | +| | `--run-id` | Run ID | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| | `--task-id` | ({{< req >}}) Task ID | string | | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +- [List all runs of a task](#list-all-runs-of-a-task) +- [List a specific run of a task](#list-a-specific-run-of-a-task) +- [Limit the number of returned task runs to 20](#limit-the-number-of-returned-task-runs-to-20) + +##### List all runs of a task +```sh +influx task run list --task-id 0Xx0oox00XXoxxoo1 +``` + +##### List a specific run of a task +```sh +influx task run list \ + --task-id 0Xx0oox00XXoxxoo1 \ + --run-id ox0Xx0ooxx00XXoo2 +``` + +##### Limit the number of returned task runs to 20 +```sh +influx task run list \ + --task-id 0Xx0oox00XXoxxoo1 \ + --limit 20 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/task/run/retry.md b/content/influxdb/v2.1/reference/cli/influx/task/run/retry.md new file mode 100644 index 0000000000..c4b44e9e8d --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/task/run/retry.md @@ -0,0 +1,45 @@ +--- +title: influx task run retry +description: The `influx task run retry` command retries to run a task in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx task run retry + parent: influx task run +weight: 301 +--- + +The `influx task run retry` command retries to run a task in InfluxDB. + +## Usage +``` +influx task run retry [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `retry` command | | | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-r` | `--run-id` | ({{< req >}}) Run ID | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-i` | `--task-id` | ({{< req >}}) Task ID | string | | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +{{% note %}} +#### Required permissions +Use an [{{% oss-only %}}**Operator** or{{% /oss-only %}} **All-Access** token](/influxdb/v2.1/security/tokens/) to retry tasks. +{{% /note %}} + +##### Retry a task run +```sh +influx task run retry \ + --task-id 0Xx0oox00XXoxxoo1 \ + --run-id ox0Xx0ooxx00XXoo2 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/task/update.md b/content/influxdb/v2.1/reference/cli/influx/task/update.md new file mode 100644 index 0000000000..ab6b1807c4 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/task/update.md @@ -0,0 +1,74 @@ +--- +title: influx task update +description: The `influx task update` command updates information related to tasks in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx task update + parent: influx task +weight: 201 +--- + +The `influx task update` command updates information related to tasks in InfluxDB. + +## Usage +``` +influx task update [task literal] [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-f` | `--file` | Path to Flux script file | string | | +| `-h` | `--help` | Help for the `update` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--http-debug` | Inspect communication with InfluxDB servers. | string | | +| `-i` | `--id` | ({{< req >}}) Task ID | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| | `--status` | Update task status (`active` or `inactive`) | string | | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Example + +{{< cli/influx-creds-note >}} + +- [Update a task from a Flux string](#update-a-task-from-a-flux-string) +- [Update a task from a Flux file](#update-a-task-from-a-flux-file) +- [Enable a task](#enable-a-task) +- [Disable a task](#disable-a-task) + +##### Update a task from a Flux string +```sh +export UPDATED_FLUX_TASK=' + option task = { + name: "Example Task", + every: 1d + } + + from(bucket: "example-bucket") + |> range(start: -task.every) + |> filter(fn: (r) => (r._measurement == "m") + |> aggregateWindow(every: 1h, fn: mean) + |> to(bucket: "default-ds-1d", org: "my-org") +' + +influx task update $UPDATED_FLUX_TASK +``` + +##### Update a task from a Flux file +```sh +influx task update --file /path/to/example-task.flux +``` + +##### Enable a task +```sh +influx task update --status active +``` + +##### Disable a task +```sh +influx task update --status inactive +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/telegrafs/_index.md b/content/influxdb/v2.1/reference/cli/influx/telegrafs/_index.md new file mode 100644 index 0000000000..ed475be0cc --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/telegrafs/_index.md @@ -0,0 +1,62 @@ +--- +title: influx telegrafs +description: > + The `influx telegrafs` command lists Telegraf configurations. + Subcommands manage Telegraf configurations. +menu: + influxdb_2_1_ref: + name: influx telegrafs + parent: influx +weight: 101 +influxdb/v2.1/tags: [telegraf] +cascade: + related: + - /influxdb/v2.1/telegraf-configs/ + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +--- + +The `influx telegrafs` command lists Telegraf configurations. +Subcommands manage Telegraf configurations. + +## Usage +```sh +influx telegrafs [flags] +influx telegrafs [command] +``` + +## Subcommands +| Subcommand | Description | +|:---------- |:----------- | +| [create](/influxdb/v2.1/reference/cli/influx/telegrafs/create) | Create a Telegraf configuration | +| [rm](/influxdb/v2.1/reference/cli/influx/telegrafs/rm) | Remove a Telegraf configuration | +| [update](/influxdb/v2.1/reference/cli/influx/telegrafs/update) | Update a Telegraf configuration | + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `telegrafs` command | | | +| | `--hide-headers` | Hide table headers | | `INFLUX_HIDE_HEADERS` | +| `-i` | `--id` | Telegraf configuration ID to retrieve | string | | +| | `--json` | Output data as JSON | | `INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### List all Telegraf configurations +```sh +influx telegrafs +``` + +##### List a Telegraf configuration with the specified ID +```sh +influx telegrafs --id 0Xx0oox00XXoxxoo1 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/telegrafs/create.md b/content/influxdb/v2.1/reference/cli/influx/telegrafs/create.md new file mode 100644 index 0000000000..7b7c93d9f8 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/telegrafs/create.md @@ -0,0 +1,54 @@ +--- + title: influx telegrafs create +description: > + The `influx telegrafs create` command creates a Telegraf configuration in InfluxDB + using a provided Telegraf configuration file. +menu: + influxdb_2_1_ref: + name: influx telegrafs create + parent: influx telegrafs +weight: 201 +--- + +The `influx telegrafs create` command creates a Telegraf configuration in InfluxDB +using a provided Telegraf configuration file. + +## Usage +```sh +influx telegrafs create [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-d` | `--description` | Telegraf configuration description | string | | +| `-f` | `--file` | Path to Telegraf configuration | string | | +| `-h` | `--help` | Help for the `create` command | | | +| | `--hide-headers` | Hide table headers | | `INFLUX_HIDE_HEADERS` | +| | `--json` | Output data as JSON | | `INFLUX_OUTPUT_JSON` | +| `-n` | `--name` | Telegraf configuration name | string | | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Create a Telegraf configuration +```sh +influx telegrafs create \ + --name "Example configuration name" \ + --description "Example Telegraf configuration description" \ + --file /path/to/telegraf.conf +``` + +##### Create a Telegraf configuration via stdin +```sh +cat /path/to/telegraf.conf | influx telegrafs create \ + --name "Example configuration name" \ + --description "Example Telegraf configuration description" \ +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/telegrafs/rm.md b/content/influxdb/v2.1/reference/cli/influx/telegrafs/rm.md new file mode 100644 index 0000000000..d36fef2562 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/telegrafs/rm.md @@ -0,0 +1,48 @@ +--- +title: influx telegrafs rm +description: > + The `influx telegrafs rm` command removes Telegraf configurations from InfluxDB. +menu: + influxdb_2_1_ref: + name: influx telegrafs rm + parent: influx telegrafs +weight: 201 +--- + +The `influx telegrafs rm` command removes Telegraf configurations from InfluxDB. + +## Usage +```sh +influx telegrafs rm [flags] +``` + +#### Command aliases +`rm`, `remove` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:-----------:|:-----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `rm` command | | | +| | `--hide-headers` | Hide the table headers | | `$INFLUX_HIDE_HEADERS` | +| `-i` | `--id` | Telegraf configuration ID to remove | stringArray | | +| | `--json` | Output data as json | | `$INFLUX_OUTPUT_JSON` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Remove a Telegraf configuration +```sh +influx telegrafs rm --id ab12cd34ef56 +``` + +##### Remove multiple Telegraf configurations +```sh +influx telegrafs rm \ + --i 0Xx0oox00XXoxxoo1 \ + --i oox0Xx0ox00XXxoo2 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/telegrafs/update.md b/content/influxdb/v2.1/reference/cli/influx/telegrafs/update.md new file mode 100644 index 0000000000..c268922405 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/telegrafs/update.md @@ -0,0 +1,56 @@ +--- +title: influx telegrafs update +description: > + The `influx telegrafs update` command updates a Telegraf configuration to match the specified parameters. + If a name or description are not provided, they are set to an empty string. +menu: + influxdb_2_1_ref: + name: influx telegrafs update + parent: influx telegrafs +weight: 201 +--- + +The `influx telegrafs update` command updates a Telegraf configuration to match the specified parameters. +If a name or description are not provided, they are set to an empty string. + +## Usage +```sh +influx telegrafs update [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-d` | `--description` | Telegraf configuration description | string | | +| `-f` | `--file` | Path to Telegraf configuration | string | | +| `-h` | `--help` | Help for the `update` command | | | +| | `--hide-headers` | Hide table headers | | `INFLUX_HIDE_HEADERS` | +| | `--json` | Output data as JSON | | `INFLUX_OUTPUT_JSON` | +| `-n` | `--name` | Telegraf configuration name | string | | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Update a Telegraf configuration +```sh +influx telegrafs update \ + --id 0Xx0oox00XXoxxoo1 \ + --name "Example configuration name" \ + --description "Example Telegraf configuration description" \ + --file /path/to/telegraf.conf +``` + +##### Update a Telegraf configuration via stdin +```sh +cat /path/to/telegraf.conf | influx telegrafs update \ + --id 0Xx0oox00XXoxxoo1 \ + --name "Example configuration name" \ + --description "Example Telegraf configuration description" \ +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/template/_index.md b/content/influxdb/v2.1/reference/cli/influx/template/_index.md new file mode 100644 index 0000000000..e7cb84b363 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/template/_index.md @@ -0,0 +1,86 @@ +--- +title: influx template +description: The `influx template` command summarizes the specified InfluxDB template. +menu: + influxdb_2_1_ref: + name: influx template + parent: influx +weight: 101 +influxdb/v2.1/tags: [templates] +aliases: + - /influxdb/v2.1/reference/cli/influx/pkg/summary/ +cascade: + related: + - /influxdb/v2.1/influxdb-templates/ + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.1+, InfluxDB 2.0.1+] +--- + +The `influx template` command summarizes the specified InfluxDB template. +The command returns information about all resources included in the template. + +## Usage +``` +influx template [flags] +influx template [command] +``` + +## Subcommands +| Subcommand | Description | +|:---------- |:----------- | +| [validate](/influxdb/v2.1/reference/cli/influx/template/validate) | Validate a template | + +## Flags +| Flag | | Description | Input Type | {{< cli/mapped >}} | +|:---- |:--- |:----------- |:---------- |:------------------ | +| | `--disable-color` | Disable color in output | | | +| | `--disable-table-borders` | Disable table borders | | | +| `-e` | `--encoding` | Template encoding (`yaml`,`yml`,`json`, or `jsonnet`) | string | | +| `-f` | `--file` | Path to template file (supports HTTP(S) URLs or file paths) | stringArray | | +| `-h` | `--help` | Help for the `template` command | | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-R` | `--recurse` | Recurse through files in the directory specified in `-f`, `--file` | | | + +## Examples + +{{< cli/influx-creds-note >}} + +**Summarize InfluxDB Templates:** + +- [from a local file](#summarize-an-influxdb-template-from-a-local-file) +- [from multiple files](#summarize-influxdb-templates-from-multiple-files) +- [from a URL](#summarize-an-influxdb-template-from-a-url) +- [from a directory](#summarize-all-influxdb-templates-in-a-directory) +- [using a specific encoding](#specify-the-encoding-of-the-influxdb-template-to-summarize) + +##### Summarize an InfluxDB template from a local file +```sh +influx template --file /path/to/template.yml +``` + +##### Summarize InfluxDB templates from multiple files +```sh +influx template \ + --file /path/to/template1.yml \ + --file /path/to/template2.yml +``` + +##### Summarize an InfluxDB template from a URL +```sh +influx template --file https://example.com/path/to/template.yml +``` + +##### Summarize all InfluxDB templates in a directory +```sh +influx template \ + --file /path/to/template/dir/ \ + --recurse +``` + +##### Specify the encoding of the InfluxDB template to summarize +```sh +influx template \ + --file /path/to/template \ + --encoding json +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/template/validate.md b/content/influxdb/v2.1/reference/cli/influx/template/validate.md new file mode 100644 index 0000000000..d4061b70fe --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/template/validate.md @@ -0,0 +1,70 @@ +--- +title: influx template validate +description: > + The `influx template validate` command validates the provided InfluxDB template. +menu: + influxdb_2_1_ref: + parent: influx template +weight: 201 +aliases: + - /influxdb/v2.1/reference/cli/influx/pkg/validate/ +--- + +The `influx template validate` command validates the provided InfluxDB template. + +## Usage +``` +influx template validate [flags] +``` + +## Flags + +| Flag | | Description | Input Type | +|:---- |:--- |:----------- |:---------- | +| `-e` | `--encoding` | Template encoding | string | +| `-f` | `--file` | Path to template file (supports HTTP(S) URLs or file paths) | stringArray | +| `-h` | `--help` | Help for the `validate` command | | +| `-R` | `--recurse` | Recurse through files in the directory specified in `-f`, `--file` | | + +## Examples + +{{< cli/influx-creds-note >}} + +**Validate InfluxDB Templates:** + +- [from a local file](#validate-an-influxdb-template-from-a-local-file) +- [from multiple files](#validate-influxdb-templates-from-multiple-files) +- [from a URL](#validate-an-influxdb-template-from-a-url) +- [from a directory](#validate-all-influxdb-templates-in-a-directory) +- [using a specific encoding](#specify-the-encoding-of-the-influxdb-template-to-validate) + +##### Validate an InfluxDB template from a local file +```sh +influx template validate --file /path/to/template.yml +``` + +##### Validate InfluxDB templates from multiple files +```sh +influx template validate \ + --file /path/to/template1.yml \ + --file /path/to/template2.yml +``` + +##### Validate an InfluxDB template from a URL +```sh +influx template validate --file https://example.com/path/to/template.yml +``` + +##### Validate all InfluxDB templates in a directory +```sh +influx template validate \ + --file /path/to/template/dir/ \ + --recurse +``` + +##### Specify the encoding of the InfluxDB template to validate +```sh +influx template validate \ + --file /path/to/template \ + --encoding json +``` \ No newline at end of file diff --git a/content/influxdb/v2.1/reference/cli/influx/transpile/_index.md b/content/influxdb/v2.1/reference/cli/influx/transpile/_index.md new file mode 100644 index 0000000000..30c8a7555f --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/transpile/_index.md @@ -0,0 +1,55 @@ +--- +title: influx transpile +description: > + The `influx transpile` command transpiles an InfluxQL query to Flux source code. +weight: 101 +related: + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions +metadata: [influx CLI 2.0.0 – 2.0.5] +prepend: + block: warn + content: | + ### Removed in InfluxDB OSS 2.0.5 + The `influx transpile` command was removed in **InfluxDB 2.0.5**. + [Use InfluxQL to query InfluxDB](/influxdb/v2.1/query-data/influxql/). + For information about manually converting InfluxQL queries to Flux, see: + + - [Get started with Flux](/flux/v0.x/get-started/) + - [Query data with Flux](/influxdb/v2.1/query-data/flux/) + - [Migrate continuous queries to Flux tasks](/influxdb/v2.1/upgrade/v1-to-v2/migrate-cqs/) +--- + +The `influx transpile` command transpiles an InfluxQL query to Flux source code. +The transpiled query assumes the bucket name is `/` +and includes absolute time ranges using the provided `--now` time. + +## Usage +``` +influx transpile [InfluxQL query] [flags] +``` + +{{% note %}} +The InfluxQL query must be valid and contain both a database and measurement. +See the [InfluxQL documentation](/{{< latest "influxdb" "v1" >}}/query_language/) for more information. +{{% /note %}} + +## Flags +| Flag | | Description | +|:---- |:--- |:----------- | +| `-h` | `--help` | Help for the `transpile` command | +| | `--now` | RFC3339Nano timestamp to use as `now()` time (default is current UTC time) | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Transpile InfluxQL queries to Flux +```sh +## Transpile an InfluxQL query that specifies the database, +## retention policy, and measurement. +influx transpile 'SELECT example-field FROM db.rp.measurement' + +## Transpile InfluxQL query using default retention policy +influx transpile 'SELECT example-field FROM db..measurement' +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/user/_index.md b/content/influxdb/v2.1/reference/cli/influx/user/_index.md new file mode 100644 index 0000000000..35ef2698fc --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/user/_index.md @@ -0,0 +1,39 @@ +--- +title: influx user +description: The `influx user` command and its subcommands manage user information in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx user + parent: influx +weight: 101 +influxdb/v2.1/tags: [users] +cascade: + related: + - /influxdb/v2.1/users/ + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +canonical: /{{< latest "influxdb" "v2" >}}/reference/cli/influx/user/ +--- + +The `influx user` command and its subcommands manage user information in InfluxDB. + +## Usage +``` +influx user [flags] +influx user [command] +``` + +## Subcommands +| Subcommand | Description | +|:---------- |:----------- | +| [create](/influxdb/v2.1/reference/cli/influx/user/create) | Create a user | +| [delete](/influxdb/v2.1/reference/cli/influx/user/delete) | Delete a user | +| [list](/influxdb/v2.1/reference/cli/influx/user/list) | List users | +| [password](/influxdb/v2.1/reference/cli/influx/user/password) | Update a user's password | +| [update](/influxdb/v2.1/reference/cli/influx/user/update) | Update a user | + +## Flags +| Flag | | Description | +|:---- |:--- |:----------- | +| `-h` | `--help` | Help for the `user` command | diff --git a/content/influxdb/v2.1/reference/cli/influx/user/create.md b/content/influxdb/v2.1/reference/cli/influx/user/create.md new file mode 100644 index 0000000000..12daa85cda --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/user/create.md @@ -0,0 +1,44 @@ +--- +title: influx user create +description: The `influx user create` command creates a user in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx user create + parent: influx user +weight: 201 +canonical: /{{< latest "influxdb" "v2" >}}/reference/cli/influx/user/create/ +--- + +The `influx user create` command creates a user in InfluxDB. + +## Usage +``` +influx user create [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `create` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-n` | `--name` | ({{< req >}}) Username | string | `INFLUX_NAME` | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| `-p` | `--password` | User password | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Create a user +```sh +influx user create \ + --name example-username \ + --password ExAmPl3PA55W0rD +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/user/delete.md b/content/influxdb/v2.1/reference/cli/influx/user/delete.md new file mode 100644 index 0000000000..dfc347c1e2 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/user/delete.md @@ -0,0 +1,39 @@ +--- +title: influx user delete +description: The `influx user delete` command deletes a specified user. +menu: + influxdb_2_1_ref: + name: influx user delete + parent: influx user +weight: 201 +canonical: /{{< latest "influxdb" "v2" >}}/reference/cli/influx/user/delete/ +--- + +The `influx user delete` command deletes a specified user in InfluxDB. + +## Usage +``` +influx user delete [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `delete` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| `-i` | `--id` | ({{< req >}}) User ID | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Delete a user +```sh +influx user delete --id 0Xx0oox00XXoxxoo1 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/user/list.md b/content/influxdb/v2.1/reference/cli/influx/user/list.md new file mode 100644 index 0000000000..0708e5db70 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/user/list.md @@ -0,0 +1,59 @@ +--- +title: influx user list +description: The `influx user list` lists users in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx user list + parent: influx user +weight: 201 +aliases: + - /influxdb/v2.1/reference/cli/influx/user/find +canonical: /{{< latest "influxdb" "v2" >}}/reference/cli/influx/user/list/ +--- + +The `influx user list` command lists users in InfluxDB. + +## Usage +``` +influx user list [flags] +``` + +#### Command aliases +`list`, `ls`, `find` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `list` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| `-i` | `--id` | User ID | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-n` | `--name` | Username | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +- [List all users](#list-all-users) +- [List a specific user by username](#list-a-specific-user-by-username) +- [List a specific user by ID](#list-a-specific-user-by-id) + +##### List all users +```sh +influx user list +``` + +##### List a specific user by username +```sh +influx user list --name example-username +``` + +##### List a specific user by ID +```sh +influx user list --id 0Xx0oox00XXoxxoo1 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/user/password.md b/content/influxdb/v2.1/reference/cli/influx/user/password.md new file mode 100644 index 0000000000..8c1925c0e8 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/user/password.md @@ -0,0 +1,48 @@ +--- +title: influx user password +description: The `influx user password` command updates the password for a user in InfluxDB. +menu: + influxdb_2_1_ref: + name: influx user password + parent: influx user +weight: 201 +related: + - /influxdb/v2.1/users/change-password/ +canonical: /{{< latest "influxdb" "v2" >}}/reference/cli/influx/user/password/ +--- + +The `influx user password` command updates the password for a user in InfluxDB. + +## Usage +``` +influx user password [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `password` command | | | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| `-i` | `--id` | User ID | string | | +| `-n` | `--name` | Username | string | | +| | `--password` | Use `password` flag to send your password instead of typing it in | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Update a user password using a username +```sh +influx user password --name example-username +# Prompts for password +``` + +##### Update a user password using a user ID +```sh +influx user password --id 0Xx0oox00XXoxxoo1 +# Prompts for password +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/user/update.md b/content/influxdb/v2.1/reference/cli/influx/user/update.md new file mode 100644 index 0000000000..bdb3e26cc8 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/user/update.md @@ -0,0 +1,43 @@ +--- +title: influx user update +description: > + The `influx user update` command updates information related to a user such as their user name. +menu: + influxdb_2_1_ref: + name: influx user update + parent: influx user +weight: 201 +canonical: /{{< latest "influxdb" "v2" >}}/reference/cli/influx/user/update/ +--- + +The `influx user update` command updates information related to a user in InfluxDB. + +## Usage +``` +influx user update [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:----------------------------------------------------------------------|:----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `update` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| `-i` | `--id` | ({{< req >}}) User ID | string | | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-n` | `--name` | Username | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Update a username +```sh +influx user update \ + --id 0Xx0oox00XXoxxoo1 \ + --name new-username +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/v1/_index.md b/content/influxdb/v2.1/reference/cli/influx/v1/_index.md new file mode 100644 index 0000000000..6f4dbb84be --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/v1/_index.md @@ -0,0 +1,36 @@ +--- +title: influx v1 +description: > + The `influx v1` command provides commands for working with the InfluxDB 1.x API in InfluxDB 2.x. +menu: + influxdb_2_1_ref: + name: influx v1 + parent: influx +weight: 101 +cascade: + related: + - /influxdb/v2.1/upgrade/v1-to-v2/ + - /influxdb/v2.1/reference/api/influxdb-1x/ + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +--- + +The `influx v1` command provides commands for working with the [InfluxDB 1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/) in InfluxDB {{< current-version >}}. + +## Usage +``` +influx v1 [flags] +influx v1 [command] +``` + +## Subcommands +| Subcommand | Description | +|:-----------------------------------------------------|:---------------------------------------------- | +| [auth](/influxdb/v2.1/reference/cli/influx/v1/auth/) | Authorization management commands for v1 APIs | +| [dbrp](/influxdb/v2.1/reference/cli/influx/v1/dbrp/) | Database retention policy mapping management commands for v1 APIs | + +## Flags +| Flag | | Description | +|:-----|:---------|:--------------------------| +| `-h` | `--help` | Help for the `v1` command | diff --git a/content/influxdb/v2.1/reference/cli/influx/v1/auth/_index.md b/content/influxdb/v2.1/reference/cli/influx/v1/auth/_index.md new file mode 100644 index 0000000000..6e6451c7a0 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/v1/auth/_index.md @@ -0,0 +1,47 @@ +--- +title: influx v1 auth +description: > + The `influx v1 auth` subcommands provide authorization management for the InfluxDB 1.x compatibility API. +menu: + influxdb_2_1_ref: + name: influx v1 auth + parent: influx v1 +weight: 101 +influxdb/v2.1/tags: [authorization] +--- + +The `influx v1 auth` subcommands provide authorization management for the +[InfluxDB 1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). + +InfluxDB {{< current-version >}} uses [API tokens](/influxdb/v2.1/security/tokens/) to authorize API requests. +The [1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/) lets clients authenticate with InfluxDB {{< current-version >}} using the InfluxDB 1.x convention of username and password. + +{{% note %}} +1.x-compatible authorizations are separate from the credentials used to log +into the InfluxDB user interface. +{{% /note %}} + +## Usage +``` +influx v1 auth [flags] +influx v1 auth [command] +``` + +#### Command aliases +`auth`, `authorization` + +## Commands + +| Command | Description | +|:----------------------------------------------------------------------------|:---------------------------------------------| +| [create](/influxdb/v2.1/reference/cli/influx/v1/auth/create/) | Create authorization | +| [delete](/influxdb/v2.1/reference/cli/influx/v1/auth/delete/) | Delete authorization | +| [list](/influxdb/v2.1/reference/cli/influx/v1/auth/list/) | List authorizations | +| [set-active](/influxdb/v2.1/reference/cli/influx/v1/auth/set-active/) | Activate an authorization | +| [set-inactive](/influxdb/v2.1/reference/cli/influx/v1/auth/set-inactive/) | Deactivate an authorization | +| [set-password](/influxdb/v2.1/reference/cli/influx/v1/auth/set-password/) | Set a password for an existing authorization | + +## Flags +| Flag | | Description | +|:-----|:---------|:--------------------------------| +| `-h` | `--help` | Help for the `v1 auth ` command | diff --git a/content/influxdb/v2.1/reference/cli/influx/v1/auth/create.md b/content/influxdb/v2.1/reference/cli/influx/v1/auth/create.md new file mode 100644 index 0000000000..feaa446e3a --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/v1/auth/create.md @@ -0,0 +1,54 @@ +--- +title: influx v1 auth create +description: > + The `influx v1 auth create` command creates an authorization in the InfluxDB 1.x compatibility API. +menu: + influxdb_2_1_ref: + name: influx v1 auth create + parent: influx v1 auth +weight: 101 +influxdb/v2.1/tags: [authorization] +updated_in: CLI v2.0.3 +--- + +The `influx v1 auth create` command creates a legacy authorization with the [InfluxDB 1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). + +## Usage +``` +influx v1 auth create [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:-----------------------------------------------------------------------------------------------------------|:-----------:|:------------------------| +| `-c` | `--active-config` | Config name to use for command | string | `$INFLUX_ACTIVE_CONFIG` | +| | `--configs-path` | Path to the influx CLI configurations (default: `~/.influxdbv2/configs`) | string | `$INFLUX_CONFIGS_PATH` | +| `-d` | `--description` | Token description | string | | +| `-h` | `--help` | Help for the `create` command | | | +| | `--hide-headers` | Hide the table headers (default: `false`) | | `$INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB | string | `$INFLUX_HOST` | +| | `--json` | Output data as JSON (default: `false`) | | `$INFLUX_OUTPUT_JSON` | +| | `--no-password` | Don't prompt for a password (to use the token, you must set a password with `influx v1 auth set-password`) | | | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `$INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `$INFLUX_ORG_ID` | +| | `--password` | Password to set on the authorization | | | +| | `--read-bucket` | Bucket ID to assign read permissions to | stringArray | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `$INFLUX_TOKEN` | +| | `--username` | ({{< req >}}) Token username | string | | +| | `--write-bucket` | Bucket ID to assign write permissions to | stringArray | | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Create a v1 authorization with read and write permissions +```sh +# Create an authorization with read and write access to bucket 00xX00o0X001 +# but only read access to bucket 00xX00o0X002 +influx v1 auth create \ + --read-bucket 00xX00o0X001 \ + --read-bucket 00xX00o0X002 \ + --write-bucket 00xX00o0X001 \ + --username example-user +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/v1/auth/delete.md b/content/influxdb/v2.1/reference/cli/influx/v1/auth/delete.md new file mode 100644 index 0000000000..04898f32ef --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/v1/auth/delete.md @@ -0,0 +1,41 @@ +--- +title: influx v1 auth delete +description: > + The `influx v1 auth delete` command deletes an authorization in the InfluxDB 1.x compatibility API. +menu: + influxdb_2_1_ref: + name: influx v1 auth delete + parent: influx v1 auth +weight: 101 +influxdb/v2.1/tags: [authorization] +--- + +The `influx v1 auth delete` command deletes an authorization in the [InfluxDB 1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). + +## Usage +``` +influx v1 auth delete [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:-------------------------------------------------------------------------|:----------:|:------------------------| +| `-c` | `--active-config` | Config name to use for command | string | `$INFLUX_ACTIVE_CONFIG` | +| | `--configs-path` | Path to the influx CLI configurations (default: `~/.influxdbv2/configs`) | string | `$INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `delete` command | | | +| | `--hide-headers` | Hide the table headers (default: `false`) | | `$INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB | string | `$INFLUX_HOST` | +| `-i` | `--id` | ({{< req >}}) Authorization ID | string | | +| | `--json` | Output data as JSON (default: `false`) | | `$INFLUX_OUTPUT_JSON` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `$INFLUX_TOKEN` | +| | `--username` | Authorization username | string | `$INFLUX_USERNAME` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Delete a v1 authorization +```sh +influx v1 auth delete --id 00xX00o0X001 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/v1/auth/list.md b/content/influxdb/v2.1/reference/cli/influx/v1/auth/list.md new file mode 100644 index 0000000000..f0ea291524 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/v1/auth/list.md @@ -0,0 +1,68 @@ +--- +title: influx v1 auth list +description: > + The `influx v1 auth list` command lists and searches authorizations in the InfluxDB 1.x compatibility API. +menu: + influxdb_2_1_ref: + name: influx v1 auth list + parent: influx v1 auth +weight: 101 +influxdb/v2.1/tags: [authorization] +--- + +The `influx v1 auth list` command lists and searches authorizations in the [InfluxDB 1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). + +## Usage +``` +influx v1 auth list [flags] +``` + +#### Command aliases +`list`, `ls`, `find` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:-------------------------------------------------------------------------|:----------:|:------------------------| +| `-c` | `--active-config` | Config name to use for command | string | `$INFLUX_ACTIVE_CONFIG` | +| | `--configs-path` | Path to the influx CLI configurations (default: `~/.influxdbv2/configs`) | string | `$INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `list` command | | | +| | `--hide-headers` | Hide the table headers (default: `false`) | | `$INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB | string | `$INFLUX_HOST` | +| `-i` | `--id` | Authorization ID | string | | +| | `--json` | Output data as JSON (default: `false`) | | `$INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `$INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `$INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `$INFLUX_TOKEN` | +| `-u` | `--user` | InfluxDB user | string | | +| | `--user-id` | InfluxDB user ID | string | | +| | `--username` | Authorization username | string | `$INFLUX_USERNAME` | + +## Examples + +{{< cli/influx-creds-note >}} + +- [List all v1 authorizations](#list-all-v1-authorizations) +- [List v1 authorizations associated with a username](#list-v1-authorizations-associated-with-a-username) +- [List v1 authorizations associated with a user ID](#list-v1-authorizations-associated-with-a-user-id) +- [List a specific v1 authorization by ID](#list-a-specific-v1-authorization-by-id) + +##### List all v1 authorizations +```sh +influx v1 auth list +``` + +##### List v1 authorizations associated with a username +```sh +influx v1 auth list --user example-username +``` + +##### List v1 authorizations associated with a user ID +```sh +influx v1 auth list --user-id 00xX00o0X001 +``` + +##### List a specific v1 authorization by ID +```sh +influx v1 auth list --id 00xX00o0X001 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/v1/auth/set-active.md b/content/influxdb/v2.1/reference/cli/influx/v1/auth/set-active.md new file mode 100644 index 0000000000..bf791abed8 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/v1/auth/set-active.md @@ -0,0 +1,42 @@ +--- +title: influx v1 auth set-active +description: > + The `influx v1 auth set-active` command activates an authorization in the InfluxDB 1.x compatibility API. +menu: + influxdb_2_1_ref: + name: influx v1 auth set-active + parent: influx v1 auth +weight: 101 +influxdb/v2.1/tags: [authorization] +--- + +The `influx v1 auth set-active` command activates an authorization in the [InfluxDB 1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). +Only active authorizations grant access to InfluxDB. + +## Usage +``` +influx v1 auth set-active [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:-------------------------------------------------------------------------|:----------:|:------------------------| +| `-c` | `--active-config` | Config name to use for command | string | `$INFLUX_ACTIVE_CONFIG` | +| | `--configs-path` | Path to the influx CLI configurations (default: `~/.influxdbv2/configs`) | string | `$INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `set-active` command | | | +| | `--hide-headers` | Hide the table headers (default: `false`) | | `$INFLUX_HIDE_HEADERS` | +| | `--host` | ({{< req >}}) HTTP address of InfluxDB | string | `$INFLUX_HOST` | +| `-i` | `--id` | Authorization ID | string | | +| | `--json` | Output data as JSON (default: `false`) | | `$INFLUX_OUTPUT_JSON` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `$INFLUX_TOKEN` | +| | `--username` | Authorization username | string | `$INFLUX_USERNAME` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Activate a v1 authorization +```sh +influx v1 auth set-active --id 00xX00o0X001 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/v1/auth/set-inactive.md b/content/influxdb/v2.1/reference/cli/influx/v1/auth/set-inactive.md new file mode 100644 index 0000000000..8667894a07 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/v1/auth/set-inactive.md @@ -0,0 +1,42 @@ +--- +title: influx v1 auth set-inactive +description: > + The `influx v1 auth set-inactive` command deactivates an authorization in the InfluxDB 1.x compatibility API. +menu: + influxdb_2_1_ref: + name: influx v1 auth set-inactive + parent: influx v1 auth +weight: 101 +influxdb/v2.1/tags: [authorization] +--- + +The `influx v1 auth set-inactive` command deactivates an authorization in the [InfluxDB 1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). +Inactive authorizations **do not** grant access to InfluxDB. + +## Usage +``` +influx v1 auth set-inactive [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:-------------------------------------------------------------------------|:----------:|:------------------------| +| `-c` | `--active-config` | Config name to use for command | string | `$INFLUX_ACTIVE_CONFIG` | +| | `--configs-path` | Path to the influx CLI configurations (default: `~/.influxdbv2/configs`) | string | `$INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `set-inactive` command | | | +| | `--hide-headers` | Hide the table headers (default: `false`) | | `$INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB | string | `$INFLUX_HOST` | +| `-i` | `--id` | ({{< req >}}) Authorization ID | string | | +| | `--json` | Output data as JSON (default: `false`) | | `$INFLUX_OUTPUT_JSON` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `$INFLUX_TOKEN` | +| | `--username` | Authorization username | string | `$INFLUX_USERNAME` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Deactivate a v1 authorization +```sh +influx v1 auth set-inactive --id 00xX00o0X001 +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/v1/auth/set-password.md b/content/influxdb/v2.1/reference/cli/influx/v1/auth/set-password.md new file mode 100644 index 0000000000..58d856e043 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/v1/auth/set-password.md @@ -0,0 +1,43 @@ +--- +title: influx v1 auth set-password +description: > + The `influx v1 auth set-password` command sets a password for an existing authorization in the InfluxDB 1.x compatibility API. +menu: + influxdb_2_1_ref: + name: influx v1 auth set-password + parent: influx v1 auth +weight: 101 +influxdb/v2.1/tags: [authorization] +updated_in: CLI v2.0.3 +--- + +The `influx v1 auth set-password` command sets a password for an existing authorization in the [InfluxDB 1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). + +## Usage +``` +influx v1 auth set-password [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:-------------------------------------------------------------------------|:----------:|:------------------------| +| `-c` | `--active-config` | Config name to use for command | string | `$INFLUX_ACTIVE_CONFIG` | +| | `--configs-path` | Path to the influx CLI configurations (default: `~/.influxdbv2/configs`) | string | `$INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `set-password` command | | | +| | `--host` | HTTP address of InfluxDB | string | `$INFLUX_HOST` | +| `-i` | `--id` | Authorization ID | string | | +| | `--password` | Password to set on the authorization | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `$INFLUX_TOKEN` | +| | `--username` | Authorization username | string | `$INFLUX_USERNAME` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Set a password for a v1 authorization +```sh +influx v1 auth set-password \ + --id 00xX00o0X001 \ + --password ExAmPl3PA55W0rD +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/v1/dbrp/_index.md b/content/influxdb/v2.1/reference/cli/influx/v1/dbrp/_index.md new file mode 100644 index 0000000000..6aef5c4d2a --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/v1/dbrp/_index.md @@ -0,0 +1,37 @@ +--- +title: influx v1 dbrp +description: > + The `influx v1 dbrp` subcommands manage database and retention policy mappings (DBRP) + for the [InfluxDB 1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). +menu: + influxdb_2_1_ref: + name: influx v1 dbrp + parent: influx v1 +weight: 101 +influxdb/v2.1/tags: [DBRP] +cascade: + metadata: [influx CLI 2.0.2+, InfluxDB 2.0.1+] +--- + +The `influx v1 dbrp` subcommands manage database and retention policy mappings (DBRP) +for the [InfluxDB 1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). + +## Usage +``` +influx v1 dbrp [flags] +influx v1 dbrp [command] +``` + +## Commands + +| Command | Description | +|:------------------------------------------------------------- |:--------------------- | +| [create](/influxdb/v2.1/reference/cli/influx/v1/dbrp/create/) | Create a DBRP mapping | +| [delete](/influxdb/v2.1/reference/cli/influx/v1/dbrp/delete/) | Delete a DBRP mapping | +| [list](/influxdb/v2.1/reference/cli/influx/v1/dbrp/list/) | List DBRP mappings | +| [update](/influxdb/v2.1/reference/cli/influx/v1/dbrp/update/) | Update a DBRP mapping | + +## Flags +| Flag | | Description | +|:-----|:---------|:--------------------------------| +| `-h` | `--help` | Help for the `v1 dbrp ` command | diff --git a/content/influxdb/v2.1/reference/cli/influx/v1/dbrp/create.md b/content/influxdb/v2.1/reference/cli/influx/v1/dbrp/create.md new file mode 100644 index 0000000000..919d108e95 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/v1/dbrp/create.md @@ -0,0 +1,50 @@ +--- +title: influx v1 dbrp create +description: > + The `influx v1 dbrp create` command creates a DBRP mapping in the InfluxDB 1.x compatibility API. +menu: + influxdb_2_1_ref: + name: influx v1 dbrp create + parent: influx v1 dbrp +weight: 101 +influxdb/v2.1/tags: [DBRP] +--- + +The `influx v1 dbrp create` command creates a DBRP mapping with the [InfluxDB 1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). + +## Usage +``` +influx v1 dbrp create [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:-------------------------------------------------------------------------|:----------:|:------------------------| +| `-c` | `--active-config` | Config name to use for command | string | `$INFLUX_ACTIVE_CONFIG` | +| | `--bucket-id` | Bucket ID to map to | | | +| | `--configs-path` | Path to the influx CLI configurations (default: `~/.influxdbv2/configs`) | string | `$INFLUX_CONFIGS_PATH` | +| | `--db` | InfluxDB v1 database to map from | | | +| | `--default` | Set DBRP mapping's retention policy as default | | | +| `-h` | `--help` | Help for the `create` command | | | +| | `--hide-headers` | Hide table headers (default: `false`) | | `$INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB | string | `$INFLUX_HOST` | +| | `--json` | Output data as JSON (default: `false`) | | `$INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `$INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `$INFLUX_ORG_ID` | +| | `--rp` | InfluxDB v1 retention policy to map from | | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `$INFLUX_TOKEN` | + + +## Examples + +{{< cli/influx-creds-note >}} + +##### Create a DBRP mapping +```sh +influx v1 dbrp create \ + --bucket-id 12ab34cd56ef \ + --db example-db \ + --rp example-rp \ + --default +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/v1/dbrp/delete.md b/content/influxdb/v2.1/reference/cli/influx/v1/dbrp/delete.md new file mode 100644 index 0000000000..bc341a1e01 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/v1/dbrp/delete.md @@ -0,0 +1,42 @@ +--- +title: influx v1 dbrp delete +description: > + The `influx v1 dbrp delete` command deletes a DBRP mapping in the InfluxDB 1.x compatibility API. +menu: + influxdb_2_1_ref: + name: influx v1 dbrp delete + parent: influx v1 dbrp +weight: 101 +influxdb/v2.1/tags: [DBRP] +--- + +The `influx v1 dbrp delete` command deletes a DBRP mapping in the [InfluxDB 1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). + +## Usage +``` +influx v1 dbrp delete [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|------|-------------------|--------------------------------------------------------------------------|------------|-------------------------| +| `-c` | `--active-config` | Config name to use for command | string | `$INFLUX_ACTIVE_CONFIG` | +| | `--configs-path` | Path to the influx CLI configurations (default: `~/.influxdbv2/configs`) | string | `$INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `delete` command | | | +| | `--hide-headers` | Hide the table headers (default: `false`) | | `$INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB | string | `$INFLUX_HOST` | +| | `--id` | ({{< req >}}) DBRP ID | string | | +| | `--json` | Output data as JSON (default: `false`) | | `$INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `$INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `$INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `$INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Delete a DBRP mapping +```sh +influx v1 dbrp delete --id 12ab34cd56ef +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/v1/dbrp/list.md b/content/influxdb/v2.1/reference/cli/influx/v1/dbrp/list.md new file mode 100644 index 0000000000..4d0fc164c9 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/v1/dbrp/list.md @@ -0,0 +1,64 @@ +--- +title: influx v1 dbrp list +description: > + The `influx v1 dbrp list` command lists and searches DBRP mappings in the InfluxDB 1.x compatibility API. +menu: + influxdb_2_1_ref: + name: influx v1 dbrp list + parent: influx v1 dbrp +weight: 101 +influxdb/v2.1/tags: [dbrp] +--- + +The `influx v1 dbrp list` command lists and searches DBRP mappings in the [InfluxDB 1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). + +## Usage +``` +influx v1 dbrp list [flags] +``` + +## Flags + +| Flag | | Description | Input type | {{< cli/mapped >}} | +|------|-------------------|--------------------------------------------------------------------------|------------|-------------------------| +| `-c` | `--active-config` | Config name to use for command | string | `$INFLUX_ACTIVE_CONFIG` | +| | `--bucket-id` | Bucket ID | | | +| | `--configs-path` | Path to the influx CLI configurations (default: `~/.influxdbv2/configs`) | string | `$INFLUX_CONFIGS_PATH` | +| | `--db` | Filter DBRP mappings by database | | | +| | `--default` | Limit results to default mapping | | | +| `-h` | `--help` | Help for the `list` command | | | +| | `--hide-headers` | Hide the table headers (default: `false`) | | `$INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB | string | `$INFLUX_HOST` | +| | `--id` | Limit results to a specified mapping | string | | +| | `--json` | Output data as JSON (default: `false`) | | `$INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `$INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `$INFLUX_ORG_ID` | +| | `--rp` | Filter DBRP mappings by InfluxDB v1 retention policy | string | `$INFLUX_ORG` | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `$INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### List all DBRP mappings in your organization +```sh +influx v1 dbrp list +``` + +##### List DBRP mappings for specific buckets +```sh +influx v1 dbrp list \ + --bucket-id 12ab34cd56ef78 \ + --bucket-id 09zy87xw65vu43 +``` + +##### List DBRP mappings with a specific database +```sh +influx v1 dbrp list --db example-db +``` + +##### List DBRP mappings with a specific retention policy +```sh +influx v1 dbrp list --rp example-rp +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/v1/dbrp/update.md b/content/influxdb/v2.1/reference/cli/influx/v1/dbrp/update.md new file mode 100644 index 0000000000..ad0aaebb57 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/v1/dbrp/update.md @@ -0,0 +1,53 @@ +--- +title: influx v1 dbrp update +description: > + The `influx v1 dbrp update` command updates a DBRP mapping in the InfluxDB 1.x compatibility API. +menu: + influxdb_2_1_ref: + name: influx v1 dbrp update + parent: influx v1 dbrp +weight: 101 +influxdb/v2.1/tags: [DBRP] +--- + +The `influx v1 dbrp update` command updates a DBRP mapping in the [InfluxDB 1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). + +## Usage +``` +influx v1 dbrp update [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:------------------|:-------------------------------------------------------------------------|:----------:|:------------------------| +| `-c` | `--active-config` | Config name to use for command | string | `$INFLUX_ACTIVE_CONFIG` | +| | `--configs-path` | Path to the influx CLI configurations (default: `~/.influxdbv2/configs`) | string | `$INFLUX_CONFIGS_PATH` | +| | `--default` | Set DBRP mapping's retention policy as default | | | +| `-h` | `--help` | Help for the `update` command | | | +| | `--hide-headers` | Hide the table headers (default: `false`) | | `$INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB | string | `$INFLUX_HOST` | +| | `--id` | ({{< req >}}) DBRP ID | string | | +| | `--json` | Output data as JSON (default: `false`) | | `$INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `$INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `$INFLUX_ORG_ID` | +| `-r` | `--rp` | InfluxDB v1 retention policy to map from | | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| `-t` | `--token` | API token | string | `$INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Set a DBRP mapping as default +```sh +influx v1 dbrp update \ + --id 12ab34cd56ef78 \ + --default +``` + +##### Update the retention policy of a DBRP mapping +```sh +influx v1 dbrp update \ + --id 12ab34cd56ef78 \ + --rp new-rp-name +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/version/_index.md b/content/influxdb/v2.1/reference/cli/influx/version/_index.md new file mode 100644 index 0000000000..f57a52bb03 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/version/_index.md @@ -0,0 +1,25 @@ +--- +title: influx version +description: The `influx version` command outputs the current version of the influx command line interface (CLI). +influxdb/v2.1/tags: [influx, cli] +menu: + influxdb_2_1_ref: + parent: influx +weight: 202 +metadata: [influx CLI 2.0.0+] +--- + +The `influx version` command outputs the current version of the `influx` +command line interface (CLI). + +## Usage + +``` +influx version [flags] +``` + +## Flags + +| Flag | | Description | +| :--- | :------- | :----------------------------- | +| `-h` | `--help` | Help for the `version` command | diff --git a/content/influxdb/v2.1/reference/cli/influx/write/_index.md b/content/influxdb/v2.1/reference/cli/influx/write/_index.md new file mode 100644 index 0000000000..0c1ad5196d --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/write/_index.md @@ -0,0 +1,289 @@ +--- +title: influx write +description: > + The `influx write` command writes data to InfluxDB via stdin or from a specified file. + Write data using line protocol, annotated CSV, or extended annotated CSV. +menu: + influxdb_2_1_ref: + name: influx write + parent: influx +weight: 101 +influxdb/v2.1/tags: [write] +cascade: + related: + - /influxdb/v2.1/write-data/ + - /influxdb/v2.1/write-data/developer-tools/csv/ + - /influxdb/v2.1/reference/syntax/line-protocol/ + - /influxdb/v2.1/reference/syntax/annotated-csv/ + - /influxdb/v2.1/reference/syntax/annotated-csv/extended/ + - /influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials + - /influxdb/v2.1/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions + metadata: [influx CLI 2.0.0+, InfluxDB 2.0.0+] +updated_in: CLI v2.0.5 +--- + +The `influx write` command writes data to InfluxDB via stdin or from a specified file. +Write data using [line protocol](/influxdb/v2.1/reference/syntax/line-protocol), +[annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv), or +[extended annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv/extended/). +If you write CSV data, CSV annotations determine how the data translates into line protocol. + + +## Usage +``` +influx write [flags] +influx write [command] +``` + +{{% note %}} +### Required data +To write data to InfluxDB, you must provide the following for each row: + +- **measurement** +- **field** +- **value** + +#### Line protocol +In **line protocol**, the [structure of the line data](/influxdb/v2.1/reference/syntax/line-protocol/#elements-of-line-protocol) +determines the measurement, field, and value. + +#### Annotated CSV +In **annotated CSV**, measurements, fields, and values are represented by the +`_measurement`, `_field`, and `_value` columns. +Their types are determined by CSV annotations. +To successfully write annotated CSV to InfluxDB, include all +[annotation rows](/influxdb/v2.1/reference/syntax/annotated-csv/#annotations). + +#### Extended annotated CSV +In **extended annotated CSV**, measurements, fields, and values and their types are determined by +[CSV annotations](/influxdb/v2.1/reference/syntax/annotated-csv/extended/#csv-annotations). +{{% /note %}} + +## Subcommands +| Subcommand | Description | +|:---------- |:----------- | +| [dryrun](/influxdb/v2.1/reference/cli/influx/write/dryrun) | Write to stdout instead of InfluxDB | + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:--------------------|:-------------------------------------------------------------------------------------------|:-----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| `-b` | `--bucket` | Bucket name (mutually exclusive with `--bucket-id`) | string | `INFLUX_BUCKET_NAME` | +| | `--bucket-id` | Bucket ID (mutually exclusive with `--bucket`) | string | `INFLUX_BUCKET_ID` | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| | `--compression` | Input compression (`none` or `gzip`, default is `none` unless input file ends with `.gz`.) | string | | +| | `--debug` | Output errors to stderr | | | +| | `--encoding` | Character encoding of input (default `UTF-8`) | string | | +| | `--error-file` | Path to a file used for recording rejected row errors | string | | +| `-f` | `--file` | File to import | stringArray | | +| | `--format` | Input format (`lp` or `csv`, default `lp`) | string | | +| | `--header` | Prepend header line to CSV input data | string | | +| `-h` | `--help` | Help for the `write` command | | | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--max-line-length` | Maximum number of bytes that can be read for a single line (default `16000000`) | integer | | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| `-p` | `--precision` | [Precision](/influxdb/v2.1/write-data/#timestamp-precision) of the timestamps (default `ns`) | string | `INFLUX_PRECISION` | +| | `--rate-limit` | Throttle write rate (examples: `5 MB / 5 min` or `1MB/s`). | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| | `--skipHeader` | Skip first *n* rows of input data | integer | | +| | `--skipRowOnError` | Output CSV errors to stderr, but continue processing | | | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | +| `-u` | `--url` | URL to import data from | stringArray | | + +## Examples + +{{< cli/influx-creds-note >}} + +###### Write line protocol + +- [via stdin](#write-line-protocol-via-stdin) +- [from a file](#write-line-protocol-from-a-file) +- [from multiple files](#write-line-protocol-from-multiple-files) +- [from a URL](#write-line-protocol-from-a-url) +- [from multiple URLs](#write-line-protocol-from-multiple-urls) +- [from multiple sources](#write-line-protocol-from-multiple-sources) +- [from a compressed file](#write-line-protocol-from-a-compressed-file) + +###### Write CSV data + +- [annotated CSV via stdin](#write-annotated-csv-data-via-stdin) +- [extended annotated CSV via stdin](#write-extended-annotated-csv-data-via-stdin) +- [from a file](#write-annotated-csv-data-from-a-file) +- [from multiple files](#write-annotated-csv-data-from-multiple-files) +- [from a URL](#write-annotated-csv-data-from-a-url) +- [from multiple URLs](#write-annotated-csv-data-from-multiple-urls) +- [from multiple sources](#write-annotated-csv-data-from-multiple-sources) +- [and prepend annotation headers](#prepend-csv-data-with-annotation-headers) +- [from a compressed file](#write-annotated-csv-data-from-a-compressed-file) +- [using rate limiting](#write-annotated-csv-data-using-rate-limiting) + +### Line protocol + +##### Write line protocol via stdin +```sh +influx write --bucket example-bucket " +m,host=host1 field1=1.2 +m,host=host2 field1=2.4 +m,host=host1 field2=5i +m,host=host2 field2=3i +" +``` + +##### Write line protocol from a file +```sh +influx write \ + --bucket example-bucket \ + --file path/to/line-protocol.txt +``` + +##### Write line protocol from multiple files +```sh +influx write \ + --bucket example-bucket \ + --file path/to/line-protocol-1.txt \ + --file path/to/line-protocol-2.txt +``` + +##### Write line protocol from a URL +```sh +influx write \ + --bucket example-bucket \ + --url https://example.com/line-protocol.txt +``` + +##### Write line protocol from multiple URLs +```sh +influx write \ + --bucket example-bucket \ + --url https://example.com/line-protocol-1.txt \ + --url https://example.com/line-protocol-2.txt +``` + +##### Write line protocol from multiple sources +```sh +influx write \ + --bucket example-bucket \ + --file path/to/line-protocol-1.txt \ + --url https://example.com/line-protocol-2.txt +``` + +##### Write line protocol from a compressed file +```sh +# The influx CLI assumes files with the .gz extension use gzip compression +influx write \ + --bucket example-bucket \ + --file path/to/line-protocol.txt.gz + +# Specify gzip compression for gzipped files without the .gz extension +influx write \ + --bucket example-bucket \ + --file path/to/line-protocol.txt.comp \ + --compression gzip +``` + +--- + +### CSV + +##### Write annotated CSV data via stdin +```sh +influx write \ + --bucket example-bucket \ + --format csv \ + "#group,false,false,false,false,true,true +#datatype,string,long,dateTime:RFC3339,double,string,string +#default,_result,,,,, +,result,table,_time,_value,_field,_measurement +,,0,2020-12-18T18:16:11Z,72.7,temp,sensorData +,,0,2020-12-18T18:16:21Z,73.8,temp,sensorData +,,0,2020-12-18T18:16:31Z,72.7,temp,sensorData +,,0,2020-12-18T18:16:41Z,72.8,temp,sensorData +,,0,2020-12-18T18:16:51Z,73.1,temp,sensorData +" +``` + +##### Write extended annotated CSV data via stdin +```sh +influx write \ + --bucket example-bucket \ + --format csv \ + "#constant measurement,sensorData +#datatype,datetime:RFC3339,double +time,temperature +2020-12-18T18:16:11Z,72.7 +2020-12-18T18:16:21Z,73.8 +2020-12-18T18:16:31Z,72.7 +2020-12-18T18:16:41Z,72.8 +2020-12-18T18:16:51Z,73.1 +" +``` + +##### Write annotated CSV data from a file +```sh +influx write \ + --bucket example-bucket \ + --file path/to/data.csv +``` + +##### Write annotated CSV data from multiple files +```sh +influx write \ + --bucket example-bucket \ + --file path/to/data-1.csv \ + --file path/to/data-2.csv +``` + +##### Write annotated CSV data from a URL +```sh +influx write \ + --bucket example-bucket \ + --url https://example.com/data.csv +``` + +##### Write annotated CSV data from multiple URLs +```sh +influx write \ + --bucket example-bucket \ + --url https://example.com/data-1.csv \ + --url https://example.com/data-2.csv +``` + +##### Write annotated CSV data from multiple sources +```sh +influx write \ + --bucket example-bucket \ + --file path/to/data-1.csv \ + --url https://example.com/data-2.csv +``` + +##### Prepend CSV data with annotation headers +```sh +influx write \ + --bucket example-bucket \ + --header "#constant measurement,birds" \ + --header "#datatype dateTime:2006-01-02,long,tag" \ + --file path/to/data.csv +``` + +##### Write annotated CSV data from a compressed file +```sh +# The influx CLI assumes files with the .gz extension use gzip compression +influx write \ + --bucket example-bucket \ + --file path/to/data.csv.gz + +# Specify gzip compression for gzipped files without the .gz extension +influx write \ + --bucket example-bucket \ + --file path/to/data.csv.comp \ + --compression gzip +``` + +##### Write annotated CSV data using rate limiting +```sh +influx write \ + --bucket example-bucket \ + --file path/to/data.csv \ + --rate-limit 5 MB / 5 min +``` diff --git a/content/influxdb/v2.1/reference/cli/influx/write/dryrun.md b/content/influxdb/v2.1/reference/cli/influx/write/dryrun.md new file mode 100644 index 0000000000..8f6a1ec02c --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influx/write/dryrun.md @@ -0,0 +1,192 @@ +--- +title: influx write dryrun +description: > + The `influx write dryrun` command prints write output to stdout instead of writing + to InfluxDB. Use this command to test writing data. +menu: + influxdb_2_1_ref: + name: influx write dryrun + parent: influx write +weight: 101 +influxdb/v2.1/tags: [write] +related: + - /influxdb/v2.1/write-data/ + - /influxdb/v2.1/write-data/developer-tools/csv/ + - /influxdb/v2.1/reference/syntax/line-protocol/ + - /influxdb/v2.1/reference/syntax/annotated-csv/ + - /influxdb/v2.1/reference/syntax/annotated-csv/extended/ +--- + +The `influx write dryrun` command prints write output to stdout instead of writing +to InfluxDB. Use this command to test writing data. + +Supports [line protocol](/influxdb/v2.1/reference/syntax/line-protocol), +[annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv), and +[extended annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv/extended). +Output is always **line protocol**. + +## Usage +``` +influx write dryrun [flags] +``` + +## Flags +| Flag | | Description | Input type | {{< cli/mapped >}} | +|:-----|:--------------------|:--------------------------------------------------------------------------------|:-----------:|:----------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| `-b` | `--bucket` | Bucket name (mutually exclusive with `--bucket-id`) | string | `INFLUX_BUCKET_NAME` | +| | `--bucket-id` | Bucket ID (mutually exclusive with `--bucket`) | string | `INFLUX_BUCKET_ID` | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string | `INFLUX_CONFIGS_PATH` | +| | `--debug` | Output errors to stderr | | | +| | `--encoding` | Character encoding of input (default `UTF-8`) | string | | +| | `--error-file` | Path to a file used for recording rejected row errors | string | | +| `-f` | `--file` | File to import | stringArray | | +| | `--format` | Input format (`lp` or `csv`, default `lp`) | string | | +| | `--header` | Prepend header line to CSV input data | string | | +| `-h` | `--help` | Help for the `dryrun` command | | | +| | `--host` | HTTP address of InfluxDB (default `http://localhost:9999`) | string | `INFLUX_HOST` | +| | `--max-line-length` | Maximum number of bytes that can be read for a single line (default `16000000`) | integer | | +| `-o` | `--org` | Organization name (mutually exclusive with `--org-id`) | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID (mutually exclusive with `--org`) | string | `INFLUX_ORG_ID` | +| `-p` | `--precision` | Precision of the timestamps (default `ns`) | string | `INFLUX_PRECISION` | +| | `--rate-limit` | Throttle write rate (examples: `5 MB / 5 min` or `1MB/s`). | string | | +| | `--skip-verify` | Skip TLS certificate verification | | `INFLUX_SKIP_VERIFY` | +| | `--skipHeader` | Skip first *n* rows of input data | integer | | +| | `--skipRowOnError` | Output CSV errors to stderr, but continue processing | | | +| `-t` | `--token` | API token | string | `INFLUX_TOKEN` | +| `-u` | `--url` | URL to import data from | stringArray | | + +## Examples + +{{< cli/influx-creds-note >}} + +- [Dry run writing line protocol](#line-protocol) + - [via stdin](#dry-run-writing-line-protocol-via-stdin) + - [from a file](#dry-run-writing-line-protocol-from-a-file) + - [from multiple files](#dry-run-writing-line-protocol-from-multiple-files) + - [from a URL](#dry-run-writing-line-protocol-from-a-url) + - [from multiple URLs](#dry-run-writing-line-protocol-from-multiple-urls) + - [from multiple sources](#dry-run-writing-line-protocol-from-multiple-sources) + +- [Dry run writing CSV data](#csv) + - [via stdin](#dry-run-writing-annotated-csv-data-via-stdin) + - [from a file](#dry-run-writing-annotated-csv-data-from-a-file) + - [from multiple files](#dry-run-writing-annotated-csv-data-from-multiple-files) + - [from a URL](#dry-run-writing-annotated-csv-data-from-a-url) + - [from multiple URLs](#dry-run-writing-annotated-csv-data-from-multiple-urls) + - [from multiple sources](#dry-run-writing-annotated-csv-data-from-multiple-sources) + - [and prepending annotation headers](#dry-run-prepending-csv-data-with-annotation-headers) + + +### Line protocol + +##### Dry run writing line protocol via stdin +```sh +influx write --bucket example-bucket " +m,host=host1 field1=1.2 +m,host=host2 field1=2.4 +m,host=host1 field2=5i +m,host=host2 field2=3i +" +``` + +##### Dry run writing line protocol from a file +```sh +influx write dryrun \ + --bucket example-bucket \ + --file path/to/line-protocol.txt +``` + +##### Dry run writing line protocol from multiple files +```sh +influx write dryrun \ + --bucket example-bucket \ + --file path/to/line-protocol-1.txt \ + --file path/to/line-protocol-2.txt +``` + +##### Dry run writing line protocol from a URL +```sh +influx write dryrun \ + --bucket example-bucket \ + --url https://example.com/line-protocol.txt +``` + +##### Dry run writing line protocol from multiple URLs +```sh +influx write dryrun \ + --bucket example-bucket \ + --url https://example.com/line-protocol-1.txt \ + --url https://example.com/line-protocol-2.txt +``` + +##### Dry run writing line protocol from multiple sources +```sh +influx write dryrun \ + --bucket example-bucket \ + --file path/to/line-protocol-1.txt \ + --url https://example.com/line-protocol-2.txt +``` + +--- + +### CSV + +##### Dry run writing annotated CSV data via stdin +```sh +influx write dryrun \ + --bucket example-bucket \ + --format csv \ + "#datatype measurement,tag,tag,field,field,ignored,time +m,cpu,host,time_steal,usage_user,nothing,time +cpu,cpu1,host1,0,2.7,a,1482669077000000000 +cpu,cpu1,host2,0,2.2,b,1482669087000000000 +" +``` + +##### Dry run writing annotated CSV data from a file +```sh +influx write dryrun \ + --bucket example-bucket \ + --file path/to/data.csv +``` + +##### Dry run writing annotated CSV data from multiple files +```sh +influx write dryrun \ + --bucket example-bucket \ + --file path/to/data-1.csv \ + --file path/to/data-2.csv +``` + +##### Dry run writing annotated CSV data from a URL +```sh +influx write dryrun \ + --bucket example-bucket \ + --url https://example.com/data.csv +``` + +##### Dry run writing annotated CSV data from multiple URLs +```sh +influx write dryrun \ + --bucket example-bucket \ + --url https://example.com/data-1.csv \ + --url https://example.com/data-2.csv +``` + +##### Dry run writing annotated CSV data from multiple sources +```sh +influx write dryrun \ + --bucket example-bucket \ + --file path/to/data-1.csv \ + --url https://example.com/data-2.csv +``` + +##### Dry run prepending CSV data with annotation headers +```sh +influx write dryrun \ + --bucket example-bucket \ + --header "#constant measurement,birds" \ + --header "#datatype dataTime:2006-01-02,long,tag" \ + --file path/to/data.csv +``` diff --git a/content/influxdb/v2.1/reference/cli/influxd/_index.md b/content/influxdb/v2.1/reference/cli/influxd/_index.md new file mode 100644 index 0000000000..b19998e495 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/_index.md @@ -0,0 +1,45 @@ +--- +title: influxd - InfluxDB service +description: The `influxd` service starts and runs all the processes necessary for InfluxDB to function. +influxdb/v2.1/tags: [influxd, cli] +menu: + influxdb_2_1_ref: + name: influxd + parent: Command line tools +weight: 102 +related: + - /influxdb/v2.1/reference/config-options/ +products: [oss] +--- + +The `influxd` daemon starts and runs all the processes necessary for InfluxDB to function. + +## Usage + +``` +influxd [flags] +influxd [command] +``` + +{{% note %}} +For information about other available InfluxDB configuration methods, see +[InfluxDB configuration options](/influxdb/v2.1/reference/config-options/). +{{% /note %}} + +## Commands + +| Command | Description | +| :----------------------------------------------------------------- | :----------------------------------------------------------- | +| [downgrade](/influxdb/v2.1/reference/cli/influxd/downgrade/) | Downgrade metadata schema to match an older release | +| help | Output help information for `influxd` | +| [inspect](/influxdb/v2.1/reference/cli/influxd/inspect/) | Inspect on-disk database data | +| [print-config](/influxdb/v2.1/reference/cli/influxd/print-config/) | Print full influxd configuration for the current environment | +| [recovery](/influxdb/v2.1/reference/cli/influxd/recovery/) | Recover operator access to InfluxDB | +| [run](/influxdb/v2.1/reference/cli/influxd/run/) | Start the influxd server _**(default)**_ | +| [upgrade](/influxdb/v2.1/reference/cli/influxd/upgrade/) | Upgrade a 1.x version of InfluxDB to {{< current-version >}} | +| [version](/influxdb/v2.1/reference/cli/influxd/version/) | Output the current version of InfluxDB | + +## Flags + + +{{< cli/influxd-flags >}} diff --git a/content/influxdb/v2.1/reference/cli/influxd/downgrade.md b/content/influxdb/v2.1/reference/cli/influxd/downgrade.md new file mode 100644 index 0000000000..f98acd0b3e --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/downgrade.md @@ -0,0 +1,48 @@ +--- +title: influxd downgrade +description: > + The `influxd downgrade` command downgrades the metadata schema used by + `influxd` to match the schema of an older release. +menu: + influxdb_2_1_ref: + parent: influxd +weight: 201 +related: + - /influxdb/v2.1/upgrade/downgrade/ +--- + +Use the `influxd downgrade` command to downgrade the metadata schema used by +`influxd` to match the metadata schema of a older release. + +InfluxDB does not guarantee backwards-compatibility with earlier releases. +Attempting to start an older `influxd` binary with a BoltDB or SQLite file that +has been migrated to a newer schema will result in a startup error. +This command downgrades metadata schemas to match the schemas of an older release +and allows the older `influxd` binary to boot successfully. + +{{% note %}} +Run this command **prior** to downgrading the `influxd` binary. +{{% /note %}} + +## Usage + +```sh +influxd downgrade [flags] +``` + +## Flags + +| Flag | | Description | Input type | +| :--- | :-------------- | :------------------------------------------------------------------------------- | :--------: | +| | `--bolt-path` | Path to BoltDB database (default is `~/.influxdbv2/influxd.bolt`) | string | +| `-h` | `--help` | Help for `downgrade` | | +| | `--log-level` | Log level (`debug`, `info` _(default_), `warn` or `error`) | string | +| | `--sqlite-path` | Path to SQLite database (default is `influxd.sqlite` in the bolt path directory) | string | + + +## Examples + +##### Downgrade to InfluxDB 2.0 +```sh +influxd downgrade 2.0 +``` \ No newline at end of file diff --git a/content/influxdb/v2.1/reference/cli/influxd/inspect/_index.md b/content/influxdb/v2.1/reference/cli/influxd/inspect/_index.md new file mode 100644 index 0000000000..0bf43a5e0a --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/inspect/_index.md @@ -0,0 +1,38 @@ +--- +title: influxd inspect +description: The `influxd inspect` commands and subcommands inspecting on-disk InfluxDB time series data. +influxdb/v2.1/tags: [inspect] +menu: + influxdb_2_1_ref: + parent: influxd +weight: 201 +--- + +The `influxd inspect` commands and subcommands inspecting on-disk InfluxDB time series data. + +## Usage +```sh +influxd inspect [subcommand] +``` + +## Subcommands +| Subcommand | Description | +| :----------------------------------------------------------------------------------- | :-------------------------------------- | +| [build-tsi](/influxdb/v2.1/reference/cli/influxd/inspect/build-tsi/) | Rebuild the TSI index and series file | +| [delete-tsm](/influxdb/v2.1/reference/cli/influxd/inspect/delete-tsm/) | Delete a measurement from a TSM file | +| [dump-tsi](/influxdb/v2.1/reference/cli/influxd/inspect/dump-tsi/) | Output low level TSI information | +| [dump-tsm](/influxdb/v2.1/reference/cli/influxd/inspect/dump-tsm/) | Output low level TSM information | +| [dump-wal](/influxdb/v2.1/reference/cli/influxd/inspect/dump-wal/) | Output TSM data from WAL files | +| [export-index](/influxdb/v2.1/reference/cli/influxd/inspect/export-index/) | Export TSI index data | +| [export-lp](/influxdb/v2.1/reference/cli/influxd/inspect/export-lp/) | Export TSM data to line protocol | +| [report-tsi](/influxdb/v2.1/reference/cli/influxd/inspect/report-tsi/) | Report the cardinality of TSI files | +| [report-tsm](/influxdb/v2.1/reference/cli/influxd/inspect/report-tsm/) | Report information about TSM files | +| [verify-seriesfile](/influxdb/v2.1/reference/cli/influxd/inspect/verify-seriesfile/) | Verify the integrity of series files | +| [verify-tombstone](/influxdb/v2.1/reference/cli/influxd/inspect/verify-tombstone/) | Verify the integrity of tombstone files | +| [verify-tsm](/influxdb/v2.1/reference/cli/influxd/inspect/verify-tsm/) | Verify the integrity of TSM files | +| [verify-wal](/influxdb/v2.1/reference/cli/influxd/inspect/verify-wal/) | Verify the integrity of WAL files | + +## Flags +| Flag | | Description | +|:---- |:--- |:----------- | +| `-h` | `--help` | Help for the `inspect` command | diff --git a/content/influxdb/v2.1/reference/cli/influxd/inspect/build-tsi.md b/content/influxdb/v2.1/reference/cli/influxd/inspect/build-tsi.md new file mode 100644 index 0000000000..6c15b405e6 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/inspect/build-tsi.md @@ -0,0 +1,59 @@ +--- +title: influxd inspect build-tsi +description: > + The `influxd inspect build-tsi` command rebuilds the TSI index and, if necessary, + the series file. +influxdb/v2.1/tags: [tsi] +menu: + influxdb_2_1_ref: + parent: influxd inspect +weight: 301 +--- + +The `influxd inspect build-tsi` command rebuilds the TSI index and, if necessary, +the series file. + +## Usage +```sh +influxd inspect build-tsi [flags] +``` + +InfluxDB builds the index by reading all Time-Structured Merge tree (TSM) indexes +and Write Ahead Log (WAL) entries in the TSM and WAL data directories. +If the series file directory is missing, it rebuilds the series file. +If the TSI index directory already exists, the command will fail. + +### Adjust performance +Use the following options to adjust the performance of the indexing process: + +##### --max-log-file-size +`--max-log-file-size` determines how much of an index to store in memory before +compacting it into memory-mappable index files. +If you find the memory requirements of your TSI index are too high, consider +decreasing this setting. + +##### --max-cache-size +`--max-cache-size` defines the maximum cache size. +The indexing process replays WAL files into a `tsm1.Cache`. +If the maximum cache size is too low, the indexing process will fail. +Increase `--max-cache-size` to account for the size of your WAL files. + +##### --batch-size +`--batch-size` defines the size of the batches written into the index. +Altering the batch size can improve performance but may result in significantly +higher memory usage. + +## Flags +| Flag | | Description | Input Type | +| :--- | :---------------------- | :---------------------------------------------------------------------------------------------- | :--------: | +| | `--batch-size` | Size of the batches to write to the index. Defaults to `10000`. [See above](#--batch-size). | integer | +| | `--bucket-id` | Bucket ID (required if `--shard-id` is present). | string | +| | `--compact-series-file` | Compact existing series file. Does not rebuilt index. | | +| | `--concurrency` | Number of workers to dedicate to shard index building. Defaults to `GOMAXPROCS` (8 by default). | integer | +| | `--data-path` | Path to the TSM data directory. Default is `~/.influxdbv2/engine/data`. | string | +| `-h` | `--help` | Help for the `build-tsi` command. | | +| | `--max-cache-size` | Maximum cache size. Defaults to `1073741824`. [See above](#--max-cache-size). | uinteger | +| | `--max-log-file-size` | Maximum log file size. Defaults to `1048576`. [See above](#--max-log-file-size) . | integer | +| | `--shard-id` | Shard ID (requires a `--bucket-id`). | string | +| `-v` | `--verbose` | Enable verbose output. | | +| | `--wal-path` | Path to the WAL data directory. Defaults to `~/.influxdbv2/engine/wal`. | string | diff --git a/content/influxdb/v2.1/reference/cli/influxd/inspect/delete-tsm.md b/content/influxdb/v2.1/reference/cli/influxd/inspect/delete-tsm.md new file mode 100644 index 0000000000..9122d55f62 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/inspect/delete-tsm.md @@ -0,0 +1,38 @@ +--- +title: influxd inspect delete-tsm +description: > + The `influxd inspect delete-tsm` command deletes a measurement from a raw TSM file. +influxdb/v2.1/tags: [tsm] +menu: + influxdb_2_1_ref: + parent: influxd inspect +weight: 301 +--- + +The `influxd inspect delete-tsm` command deletes a measurement from a raw TSM file. + +## Usage +```sh +influxd inspect delete-tsm [flags] +``` + +## Flags +| Flag | | Description | Input Type | +| :--- | :-------------- | :---------------------------------------------------- | :--------: | +| `-h` | `--help` | Help for `delete-tsm` | | +| | `--measurement` | Name of the measurement to delete | string | +| | `--sanitize` | Remove all keys with non-printable unicode characters | | +| `-v` | `--verbose` | Enable verbose logging | | + +## Examples + +##### Delete a measurement from a TSM file +```sh +influxd inspect delete-tsm \ + --measurement example-measurement +``` + +##### Remove non-printable unicode characters from all TSM files +```sh +influxd inspect delete-tsm --sanitize +``` diff --git a/content/influxdb/v2.1/reference/cli/influxd/inspect/dump-tsi.md b/content/influxdb/v2.1/reference/cli/influxd/inspect/dump-tsi.md new file mode 100644 index 0000000000..7e3d843e65 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/inspect/dump-tsi.md @@ -0,0 +1,32 @@ +--- +title: influxd inspect dump-tsi +description: > + The `influxd inspect dump-tsi` command outputs low-level information about `tsi1` files. +influxdb/v2.1/tags: [tsi, inspect] +menu: + influxdb_2_1_ref: + parent: influxd inspect +weight: 301 +--- + +The `influxd inspect dump-tsi` command outputs low-level information about +Time Series Index (`tsi1`) files. + +## Usage +```sh +influxd inspect dump-tsi [flags] +``` + +## Flags +| Flag | | Description | Input Type | +| :--- | :--------------------- | :------------------------------------- | :--------: | +| `-h` | `--help` | Help for the `dump-tsi` command. | | +| | `--measurement-filter` | Regular expression measurement filter. | string | +| | `--measurements` | Show raw measurement data. | | +| | `--series` | Show raw series data. | | +| | `--series-file` | Path to series file. | string | +| | `--tag-key-filter` | Regular expression tag key filter. | string | +| | `--tag-keys` | Show raw tag key data. | | +| | `--tag-value-filter` | Regular expression tag value filter. | string | +| | `--tag-value-series` | Show raw series data for each value. | | +| | `--tag-values` | Show raw tag value data. | | diff --git a/content/influxdb/v2.1/reference/cli/influxd/inspect/dump-tsm.md b/content/influxdb/v2.1/reference/cli/influxd/inspect/dump-tsm.md new file mode 100644 index 0000000000..abc567e3a3 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/inspect/dump-tsm.md @@ -0,0 +1,30 @@ +--- +title: influxd inspect dump-tsm +description: > + The `influxd inspect dump-tsm` command outputs low-level information about `tsi1` files. +influxdb/v2.1/tags: [tsm, inspect] +menu: + influxdb_2_1_ref: + parent: influxd inspect +weight: 301 +--- + +The `influxd inspect dump-tsm` command outputs low-level information about +Time Series Merge Tree (`tsm1`) files. + +## Usage +```sh +influxd inspect dump-tsm [flags] +``` + +## Flags +| Flag | | Description | Input Type | +| :--- | :------------- | :--------------------------------------------- | :--------: | +| | `--all` | Output all TSM data {{< req " \*" >}} | | +| | `--blocks` | Output raw block data. | | +| | `--file-path` | Path to TSM file. | string | +| | `--filter-key` | Only display data matching this key substring. | string | +| `-h` | `--help` | Help for `dump-tsm`. | | +| | `--index` | Dump raw index data. | | + +_{{< req "\*" >}} Using the `--all` flag may print a significant amount of information._ diff --git a/content/influxdb/v2.1/reference/cli/influxd/inspect/dump-wal.md b/content/influxdb/v2.1/reference/cli/influxd/inspect/dump-wal.md new file mode 100644 index 0000000000..70e995ceba --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/inspect/dump-wal.md @@ -0,0 +1,43 @@ +--- +title: influxd inspect dump-wal +description: > + The `influxd inspect dump-wal` command outputs data from WAL files for debugging purposes. +influxdb/v2.1/tags: [wal, inspect] +menu: + influxdb_2_1_ref: + parent: influxd inspect +weight: 301 +--- + +The `influxd inspect dump-wal` command outputs data from Write Ahead Log (WAL) +files for debugging purposes. +Given at least one WAL file path as an argument, the tool parses and prints +out the entries in each file. + +## Usage +```sh +influxd inspect dump-wal [flags] +``` + +## Output details +The `--find-duplicates` flag determines the `influxd inspect dump-wal` output. + +**Without `--find-duplicates`**, the command outputs the following for each file: + +- The file name +- For each entry in a file: + - The type of the entry (`[write]` or `[delete-bucket-range]`) + - The formatted entry contents + +**With `--find-duplicates`**, the command outputs the following for each file): + +- The file name +- A list of keys with timestamps in the wrong order + + + +## Flags +| Flag | | Description | +|:---- |:--- |:----------- | +| | `--find-duplicates` | Ignore dumping entries; only report keys in the WAL that are out of order. | +| `-h` | `--help` | Help for the `dump-wal` command. | diff --git a/content/influxdb/v2.1/reference/cli/influxd/inspect/export-index.md b/content/influxdb/v2.1/reference/cli/influxd/inspect/export-index.md new file mode 100644 index 0000000000..517b6f907f --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/inspect/export-index.md @@ -0,0 +1,26 @@ +--- +title: influxd inspect export-index +description: > + The `influxd inspect export-index` command exports all series in a TSI index to + SQL format for inspection and debugging. +influxdb/v2.1/tags: [inspect] +menu: + influxdb_2_1_ref: + parent: influxd inspect +weight: 301 +--- + +The `influxd inspect export-index` command exports all series in a TSI index to +SQL format for inspection and debugging. + +## Usage +```sh +influxd inspect export-index [flags] +``` + +## Flags +| Flag | | Description | Input type | +|:---- |:--- |:----------- |:----------:| +| `-h` | `--help` | Help for the `export-index` command. | | +| |`--index-path` | Path to the index directory. Defaults to `~/.influxdbv2/engine/index`). | string | +| |`--series-path` | Path to series file. Defaults to `~/.influxdbv2/engine/_series`). | string | diff --git a/content/influxdb/v2.1/reference/cli/influxd/inspect/export-lp.md b/content/influxdb/v2.1/reference/cli/influxd/inspect/export-lp.md new file mode 100644 index 0000000000..7a15d280fc --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/inspect/export-lp.md @@ -0,0 +1,133 @@ +--- +title: influxd inspect export-lp +description: > + The `influxd inspect export-lp` command exports all time series data in a bucket + as line protocol. +influxdb/v2.1/tags: [inspect, export] +menu: + influxdb_2_1_ref: + parent: influxd inspect +weight: 301 +--- + +The `influxd inspect export-lp` command exports all time-structured merge tree (TSM) +data in a bucket to [line protocol](/influxdb/v2.1/reference/syntax/line-protocol/). + +## Usage +```sh +influxd inspect export-lp [flags] +``` + +## Flags +| Flag | | Description | Input type | +|:---- |:--- |:----------- |:----------:| +| | `--bucket-id` | ({{< req >}}) Bucket ID | string | +| | `--compress` | Compress output with GZIP | | +| | `--end` | End time to export (RFC3339 format) | string | +| | `--engine-path` | ({{< req >}}) Path to persistent InfluxDB engine files | string | +| `-h` | `--help` | Help for the `export-lp` command. | | +| | `--log-level` | Log-level (`debug`, `info` _(default)_, or `error`) | string | +| | `--measurement` | Measurement name(s) to export | strings | +| | `--output-path` | ({{< req >}}) Output path (file path or stdout _(`-`)_) | string | +| | `--start` | Start time to export (RFC3339 format) | string | + +## Examples + +- [Export all data in a bucket as line protocol](#export-all-data-in-a-bucket-as-line-protocol) +- [Export data in measurements as line protocol](#export-data-in-measurements-as-line-protocol) +- [Export data in specified time range as line protocol](#export-data-in-specified-time-range-as-line-protocol) + +##### Export all data in a bucket as line protocol +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[To a file](#) +[To stdout](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +influxd inspect export-lp \ + --bucket-id 12ab34cd56ef \ + --engine-path ~/.influxdbv2/engine \ + --output-path path/to/export.lp +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sh +influxd inspect export-lp \ + --bucket-id 12ab34cd56ef \ + --engine-path ~/.influxdbv2/engine \ + --output-path - +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +##### Export data in measurements as line protocol + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[To a file](#) +[To stdout](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +# Export a single measurement +influxd inspect export-lp \ + --bucket-id 12ab34cd56ef \ + --engine-path ~/.influxdbv2/engine \ + --measurement example-measurement \ + --output-path path/to/export.lp + +# Export multiple measurements +influxd inspect export-lp \ + --bucket-id 12ab34cd56ef \ + --engine-path ~/.influxdbv2/engine \ + --measurement example-measurement-1 example-measurement-2 \ + --output-path path/to/export.lp +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sh +# Export a single measurement +influxd inspect export-lp \ + --bucket-id 12ab34cd56ef \ + --engine-path ~/.influxdbv2/engine \ + --measurement example-measurement \ + --output-path - + +# Export multiple measurements +influxd inspect export-lp \ + --bucket-id 12ab34cd56ef \ + --engine-path ~/.influxdbv2/engine \ + --measurement example-measurement-1 example-measurement-2 \ + --output-path - +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +##### Export data in specified time range as line protocol +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[To a file](#) +[To stdout](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +influxd inspect export-lp \ + --bucket-id 12ab34cd56ef \ + --engine-path ~/.influxdbv2/engine \ + --start 2021-01-01T00:00:00Z \ + --end 2021-01-31T23:59:59Z \ + --output-path path/to/export.lp +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sh +influxd inspect export-lp \ + --bucket-id 12ab34cd56ef \ + --engine-path ~/.influxdbv2/engine \ + --start 2021-01-01T00:00:00Z \ + --end 2021-01-31T23:59:59Z \ + --output-path - +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} diff --git a/content/influxdb/v2.1/reference/cli/influxd/inspect/report-tsi.md b/content/influxdb/v2.1/reference/cli/influxd/inspect/report-tsi.md new file mode 100644 index 0000000000..e226919d5d --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/inspect/report-tsi.md @@ -0,0 +1,29 @@ +--- +title: influxd inspect report-tsi +description: > + The `influxd inspect report-tsi` command analyzes Time Series Index (TSI) files + in a storage directory and reports the cardinality of data stored in the files. +influxdb/v2.1/tags: [tsi, cardinality, inspect] +menu: + influxdb_2_1_ref: + parent: influxd inspect +weight: 301 +--- + +The `influxd inspect report-tsi` command analyzes Time Series Index (TSI) within +a specified bucket and reports the cardinality of data stored in the bucket +segmented by shard and measurement. + +## Usage +```sh +influxd inspect report-tsi [flags] +``` + +## Flags +| Flag | | Description | Input Type | +| :---- | :--------------- | :------------------------------------------------------------------------------------------- | :--------: | +| `-b` | `--bucket-id` | ({{< req >}}) Process data for specified bucket ID. | string | +| `-c ` | `--concurrency` | Number of workers to run concurrently (default is the number of available processing units). | integer | +| | `--data-path` | Path to data directory (default `~/.influxdbv2/engine/data`). | string | +| `-h` | `--help` | View Help for the `report-tsi` command. | | +| `-t` | `-top` | Limit results to the top n. | integer | diff --git a/content/influxdb/v2.1/reference/cli/influxd/inspect/report-tsm.md b/content/influxdb/v2.1/reference/cli/influxd/inspect/report-tsm.md new file mode 100644 index 0000000000..2150aee297 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/inspect/report-tsm.md @@ -0,0 +1,55 @@ +--- +title: influxd inspect report-tsm +description: > + The `influxd inspect report-tsm` command analyzes Time-Structured Merge Tree (TSM) + files within a storage engine directory and reports the cardinality within the files + and the time range the data covers. +influxdb/v2.1/tags: [tsm, cardinality, inspect] +menu: + influxdb_2_1_ref: + parent: influxd inspect +weight: 301 +--- + +The `influxd inspect report-tsm` command analyzes Time-Structured Merge Tree (TSM) +files within a storage engine directory and reports the cardinality within the files +and the time range the data covers. + +This command only reports on the index within each TSM file. +It does not read any block data. +To reduce heap requirements, by default `report-tsm` estimates the overall +cardinality in the file set by using the HLL++ algorithm. +Determine exact cardinalities by using the `--exact` flag. + +## Usage +```sh +influxd inspect report-tsm [flags] +``` + +## Output details +`influxd inspect report-tsm` outputs the following for each TSM file: + +- The full file name. +- The series cardinality within the file. +- The number of series first encountered within the file. +- The minimum and maximum timestamp associated with TSM data in the file. +- The time to load the TSM index and apply any tombstones. + +The summary section then outputs the total time range and series cardinality for +the file set. Depending on the `--detailed` flag, series cardinality is segmented +in the following ways: + +- Series cardinality for each organization. +- Series cardinality for each bucket. +- Series cardinality for each measurement. +- Number of field keys for each measurement. +- Number of tag values for each tag key. + +## Flags +| Flag | | Description | Input Type | +| :--- | :------------ | :----------------------------------------------------------------------------------------------- | :--------: | +| | `--data-path` | Path to data directory (defaults to `~/.influxdbv2/engine/data`). | string | +| | `--detailed` | Emit series cardinality segmented by measurements, tag keys, and fields. _**May take a while**_. | | +| | `--exact` | Calculate an exact cardinality count. _**May use significant memory**_. | | +| `-h` | `--help` | Help for the `report-tsm` command. | | +| | `--pattern` | Only process TSM files containing pattern. | string | diff --git a/content/influxdb/v2.1/reference/cli/influxd/inspect/verify-seriesfile.md b/content/influxdb/v2.1/reference/cli/influxd/inspect/verify-seriesfile.md new file mode 100644 index 0000000000..0c96e8a6ec --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/inspect/verify-seriesfile.md @@ -0,0 +1,27 @@ +--- +title: influxd inspect verify-seriesfile +description: > + The `influxd inspect verify-seriesfile` command verifies the integrity of series files. +influxdb/v2.1/tags: [inspect] +menu: + influxdb_2_1_ref: + parent: influxd inspect +weight: 301 +--- + +The `influxd inspect verify-seriesfile` command verifies the integrity of series files. + +## Usage +```sh +influxd inspect verify-seriesfile [flags] +``` + +## Flags +| Flag | | Description | Input Type | +| :--- | :-------------- | :-------------------------------------------------------------------------------------------- | :--------: | +| | `--bucket-id` | Verify series files from a specific bucket. | string | +| `-c` | `--concurrency` | Number of workers to run concurrently (defaults to the number of available processing units). | integer | +| | `--data-path` | Path to data directory (defaults to `~/.influxdbv2/engine/data`). | string | +| `-h` | `--help` | Help for the `verify-seriesfile` command. | | +| | `--series-path` | Path to series file (overrides `--data-path` and `--bucket-id`). | string | +| `-v` | `--verbose` | Enable verbose output. | | diff --git a/content/influxdb/v2.1/reference/cli/influxd/inspect/verify-tombstone.md b/content/influxdb/v2.1/reference/cli/influxd/inspect/verify-tombstone.md new file mode 100644 index 0000000000..bfebae006a --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/inspect/verify-tombstone.md @@ -0,0 +1,25 @@ +--- +title: influxd inspect verify-tombstone +description: > + The `influxd inspect verify-tombstone` command verifies the integrity of tombstone files. +influxdb/v2.1/tags: [inspect] +menu: + influxdb_2_1_ref: + parent: influxd inspect +weight: 301 +--- + +The `influxd inspect verify-tombstone` command verifies the integrity of tombstone files. + +## Usage +```sh +influxd inspect verify-tombstone [flags] +``` + +## Flags +| Flag | | Description | Input Type | +| :--- | :-------------- | :------------------------------------------------------------------- | :--------: | +| | `--engine-path` | Path to find tombstone files (defaults to `~/.influxdbv2/engine`). | string | +| `-h` | `--help` | Help for `verify-tombstone`. | | +| `-v` | `--verbose` | Verbose output (emit periodic progress). | | +| | `--vv` | Very verbose output (emit every tombstone entry key and time range). | | diff --git a/content/influxdb/v2.1/reference/cli/influxd/inspect/verify-tsm.md b/content/influxdb/v2.1/reference/cli/influxd/inspect/verify-tsm.md new file mode 100644 index 0000000000..7e19d3d69d --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/inspect/verify-tsm.md @@ -0,0 +1,26 @@ +--- +title: influxd inspect verify-tsm +description: > + The `influxd inspect verify-tsm` command analyzes a set of TSM files for inconsistencies + between the TSM index and the blocks. +influxdb/v2.1/tags: [tsm, inspect] +menu: + influxdb_2_1_ref: + parent: influxd inspect +weight: 301 +--- + +The `influxd inspect verify-tsm` command verifies the integrity of TSM files. + +## Usage +```sh +influxd inspect verify-tsm [flags] +``` + +## Flags +| Flag | | Description | Input Type | +| :--- | :-------------- | :---------------------------------------------------------------------- | :--------: | +| | `--check-utf8` | Verify series keys are valid UTF-8 (skips block checksum verification). | | +| | `--engine-path` | Storage engine directory path (default is `~/.influxdbv2/engine`). | string | +| `-h` | `--help` | Help for `verify-tsm`. | | +| `-v` | `--verbose` | Enable verbose logging. | | diff --git a/content/influxdb/v2.1/reference/cli/influxd/inspect/verify-wal.md b/content/influxdb/v2.1/reference/cli/influxd/inspect/verify-wal.md new file mode 100644 index 0000000000..bd6f1435b4 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/inspect/verify-wal.md @@ -0,0 +1,40 @@ +--- +title: influxd inspect verify-wal +description: > + The `influxd inspect verify-wal` command analyzes the Write-Ahead Log (WAL) + to check if there are any corrupt files. +influxdb/v2.1/tags: [wal, inspect] +menu: + influxdb_2_1_ref: + parent: influxd inspect +weight: 301 +--- + +The `influxd inspect verify-wal` command analyzes the Write-Ahead Log (WAL) +to check if there are any corrupt files. +If it finds corrupt files, the command returns the names of those files. +It also returns the total number of entries in each scanned WAL file. + +## Usage +```sh +influxd inspect verify-wal [flags] +``` + +## Output details +`influxd inspect verify-wal` outputs the following for each file: + +- The file name. +- The first position of any identified corruption or "clean" if no corruption is found. + +After the verification is complete, it returns a summary with: + +- The number of WAL files scanned. +- The number of WAL entries scanned. +- A list of files found to be corrupt. + +## Flags +| Flag | | Description | Input Type | +| :--- | :----------- | :------------------------------------------------------------ | :--------: | +| `-h` | `--help` | Help for the `verify-wal` command. | | +| `-v` | `--verbose` | Enable verbose logging. | | +| | `--wal-path` | Path to WAL directory (default is `~/.influxdbv2/engine/wal`) | string | diff --git a/content/influxdb/v2.1/reference/cli/influxd/print-config.md b/content/influxdb/v2.1/reference/cli/influxd/print-config.md new file mode 100644 index 0000000000..bd41818cb7 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/print-config.md @@ -0,0 +1,49 @@ +--- +title: influxd print-config +description: > + The `influxd print-config` command prints a full InfluxDB configuration resolved + from the current `influxd` environment. +influxdb/v2.1/tags: [influxd, cli] +menu: + influxdb_2_1_ref: + parent: influxd +weight: 201 +related: + - /influxdb/v2.1/reference/config-options/ +--- + +The `influxd print-config` command prints a full InfluxDB configuration resolved +from the current `influxd` environment. +The command formats output as YAML. + +## Usage + +``` +influxd print-config [flags] +``` + + +{{% note %}} +For information about available InfluxDB configuration methods, see +[InfluxDB configuration options](/influxdb/v2.1/reference/config-options/). +{{% /note %}} + +## Flags + +| Flag | | Description | Input type | +|:---- | --- |:----------- |:----------:| +| `-h` | `--help` | Help for `print-config` | | +| | `--key-name` | Print the value of a specific configuration key | string | + + +## Examples + +##### Print full influxd configuration +```sh +influxd print-config +``` + +##### Print the value of a specific influxd configuration setting +```sh +influxd print-config --key-name=http-bind-address +``` diff --git a/content/influxdb/v2.1/reference/cli/influxd/recovery/_index.md b/content/influxdb/v2.1/reference/cli/influxd/recovery/_index.md new file mode 100644 index 0000000000..81e41c1d4b --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/recovery/_index.md @@ -0,0 +1,33 @@ +--- +title: influxd recovery +description: > + The `influxd recovery` command and subcommands provide tools for recovering + operator access to InfluxDB by directly modifying authorization, organization, + and user data stored on disk. +menu: + influxdb_2_1_ref: + parent: influxd +weight: 201 +--- + +The `influxd recovery` command and subcommands provide tools for recovering +operator access to InfluxDB by directly modifying authorization, organization, +and user data stored on disk. + +## Usage +```sh +influxd recovery [flags] +influxd recovery [command] +``` + +## Subcommands +| Subcommand | Description | +| :---------------------------------------------------------- | :--------------------------------------------- | +| [auth](/influxdb/v2.1/reference/cli/influxd/recovery/auth/) | Manage on-disk authorization data for recovery | +| [org](/influxdb/v2.1/reference/cli/influxd/recovery/org/) | Manage on-disk organization data for recovery | +| [user](/influxdb/v2.1/reference/cli/influxd/recovery/user/) | Manage on-disk user data for recovery | + +## Flags +| Flag | | Description | +| :--- | :------- | :------------------ | +| `-h` | `--help` | Help for `recovery` | \ No newline at end of file diff --git a/content/influxdb/v2.1/reference/cli/influxd/recovery/auth/_index.md b/content/influxdb/v2.1/reference/cli/influxd/recovery/auth/_index.md new file mode 100644 index 0000000000..bf4e4fa4d1 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/recovery/auth/_index.md @@ -0,0 +1,30 @@ +--- +title: influxd recovery auth +description: > + The `influxd recovery auth` command and subcommands manage on-disk authorization + data for recovery purposes. +menu: + influxdb_2_1_ref: + parent: influxd recovery +weight: 301 +--- + +The `influxd recovery auth` command and subcommands manage on-disk authorization +data for recovery purposes. + +## Usage +```sh +influxd recovery auth [flags] +influxd recovery auth [command] +``` + +## Subcommands +| Subcommand | Description | +| :------------------------------------------------------------------------------------- | :----------------------------------- | +| [create-operator](/influxdb/v2.1/reference/cli/influxd/recovery/auth/create-operator/) | Create new operator token for a user | +| [list](/influxdb/v2.1/reference/cli/influxd/recovery/auth/list/) | List authorizations | + +## Flags +| Flag | | Description | +| :---- | :------- | :-------------- | +| `-h ` | `--help` | Help for `auth` | \ No newline at end of file diff --git a/content/influxdb/v2.1/reference/cli/influxd/recovery/auth/create-operator.md b/content/influxdb/v2.1/reference/cli/influxd/recovery/auth/create-operator.md new file mode 100644 index 0000000000..a061874078 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/recovery/auth/create-operator.md @@ -0,0 +1,41 @@ +--- +title: influxd recovery auth create-operator +description: > + The `influxd recovery auth create-operator` command creates new + [Operator token](/influxdb/v2.1/security/tokens/#operator-token) directly on disk + for a specified user. +menu: + influxdb_2_1_ref: + parent: influxd recovery auth +weight: 401 +--- + +The `influxd recovery auth create-operator` command creates a new +[Operator token](/influxdb/v2.1/security/tokens/#operator-token) directly on disk +for a specified user. + +{{% note %}} +This command can only be executed when the InfluxDB server (`influxd`) is not running. +{{% /note %}} + +## Usage +```sh +influxd recovery auth create-operator [flags] +``` + +## Flags +| Flag | | Description | Input Type | +| :--- | :------------ | :------------------------------------------------------------- | :--------: | +| | `--bolt-path` | Path to the BoltDB file (default `~/.influxdbv2/influxd.bolt`) | string | +| `-h` | `--help` | Help for `create-operator` | | +| | `--org` | ({{< req >}}) Organization name | string | +| | `--username` | ({{< req >}}) Username to assign the operator token to | string | + +## Examples + +##### Generate a new operator token +```sh +influxd \ + --org example-org \ + --username example-user +``` \ No newline at end of file diff --git a/content/influxdb/v2.1/reference/cli/influxd/recovery/auth/list.md b/content/influxdb/v2.1/reference/cli/influxd/recovery/auth/list.md new file mode 100644 index 0000000000..f6c2fe6052 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/recovery/auth/list.md @@ -0,0 +1,28 @@ +--- +title: influxd recovery auth list +description: > + The `influxd recovery auth list` command lists authorizations and data + associated with each authorization stored on disk. +menu: + influxdb_2_1_ref: + parent: influxd recovery auth +weight: 401 +--- + +The `influxd recovery org list` command lists authorizations stored on disk and +outputs data associated with each authorization. + +{{% note %}} +This command can only be executed when the InfluxDB server (`influxd`) is not running. +{{% /note %}} + +## Usage +```sh +influxd recovery auth list [flags] +``` + +## Flags +| Flag | | Description | Input Type | +| :--- | :------------ | :------------------------------------------------------------- | :--------: | +| | `--bolt-path` | Path to the BoltDB file (default `~/.influxdbv2/influxd.bolt`) | string | +| `-h` | `--help` | Help for `list` | | \ No newline at end of file diff --git a/content/influxdb/v2.1/reference/cli/influxd/recovery/org/_index.md b/content/influxdb/v2.1/reference/cli/influxd/recovery/org/_index.md new file mode 100644 index 0000000000..26ce622105 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/recovery/org/_index.md @@ -0,0 +1,30 @@ +--- +title: influxd recovery org +description: > + The `influxd recovery org` command and subcommands manage on-disk organization + data for recovery purposes. +menu: + influxdb_2_1_ref: + parent: influxd recovery +weight: 301 +--- + +The `influxd recovery org` command and subcommands manage on-disk organization +data for recovery purposes. + +## Usage +```sh +influxd recovery org [flags] +influxd recovery org [command] +``` + +## Subcommands +| Subcommand | Description | +| :------------------------------------------------------------------ | :----------------- | +| [create](/influxdb/v2.1/reference/cli/influxd/recovery/org/create/) | Create new org | +| [list](/influxdb/v2.1/reference/cli/influxd/recovery/org/list/) | List organizations | + +## Flags +| Flag | | Description | +| :--- | :------- | :------------- | +| `-h` | `--help` | Help for `org` | \ No newline at end of file diff --git a/content/influxdb/v2.1/reference/cli/influxd/recovery/org/create.md b/content/influxdb/v2.1/reference/cli/influxd/recovery/org/create.md new file mode 100644 index 0000000000..4f67323dbb --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/recovery/org/create.md @@ -0,0 +1,36 @@ +--- +title: influxd recovery org create +description: > + The `influxd recovery org create` command creates a new organization directly + on disk for recovery purposes. +menu: + influxdb_2_1_ref: + parent: influxd recovery org +weight: 401 +--- + +The `influxd recovery org create` command creates a new organization directly +on disk for recovery purposes. + +{{% note %}} +This command can only be executed when the InfluxDB server (`influxd`) is not running. +{{% /note %}} + +## Usage +```sh +influxd recovery org create [flags] +``` + +## Flags +| Flag | | Description | Input Type | +| :--- | :------------ | :------------------------------------------------------------- | :--------: | +| | `--bolt-path` | Path to the BoltDB file (default `~/.influxdbv2/influxd.bolt`) | string | +| `-h` | `--help` | Help for `create` | | +| | `--org` | Organization name | string | + +## Examples + +##### Create a new organization directly on disk +```sh +influxd recovery org create --org example-org +``` \ No newline at end of file diff --git a/content/influxdb/v2.1/reference/cli/influxd/recovery/org/list.md b/content/influxdb/v2.1/reference/cli/influxd/recovery/org/list.md new file mode 100644 index 0000000000..0ac86a010d --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/recovery/org/list.md @@ -0,0 +1,28 @@ +--- +title: influxd recovery org list +description: > + The `influxd recovery org list` command lists organizations stored on disk and + outputs data associated with each organization. +menu: + influxdb_2_1_ref: + parent: influxd recovery org +weight: 401 +--- + +The `influxd recovery org list` command lists organizations stored on disk and +outputs data associated with each organization. + +{{% note %}} +This command can only be executed when the InfluxDB server (`influxd`) is not running. +{{% /note %}} + +## Usage +```sh +influxd recovery org list [flags] +``` + +## Flags +| Flag | | Description | Input Type | +| :--- | :------------ | :------------------------------------------------------------- | :--------: | +| | `--bolt-path` | Path to the BoltDB file (default `~/.influxdbv2/influxd.bolt`) | string | +| `-h` | `--help` | Help for `list` | | \ No newline at end of file diff --git a/content/influxdb/v2.1/reference/cli/influxd/recovery/user/_index.md b/content/influxdb/v2.1/reference/cli/influxd/recovery/user/_index.md new file mode 100644 index 0000000000..f1b20fba8d --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/recovery/user/_index.md @@ -0,0 +1,31 @@ +--- +title: influxd recovery user +description: > + The `influxd recovery user` command and subcommands manage on-disk user + data for recovery purposes. +menu: +menu: + influxdb_2_1_ref: + parent: influxd recovery +weight: 301 +--- + +The `influxd recovery user` command and subcommands manage on-disk user +data for recovery purposes. + +## Usage +```sh +influxd recovery user [flags] +influxd recovery user [command] +``` + +## Subcommands +| Subcommand | Description | +| :------------------------------------------------------------------- | :-------------- | +| [create](/influxdb/v2.1/reference/cli/influxd/recovery/user/create/) | Create new user | +| [list](/influxdb/v2.1/reference/cli/influxd/recovery/user/list/) | List users | + +## Flags +| Flag | | Description | +| :--- | :------- | :-------------- | +| `-h` | `--help` | Help for `user` | \ No newline at end of file diff --git a/content/influxdb/v2.1/reference/cli/influxd/recovery/user/create.md b/content/influxdb/v2.1/reference/cli/influxd/recovery/user/create.md new file mode 100644 index 0000000000..d9d4a76b9d --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/recovery/user/create.md @@ -0,0 +1,39 @@ +--- +title: influxd recovery user create +description: > + The `influxd recovery user create` command creates a new user directly + on disk for recovery purposes. +menu: + influxdb_2_1_ref: + parent: influxd recovery user +weight: 401 +--- + +The `influxd recovery user create` command creates a new user directly +on disk for recovery purposes. + +{{% note %}} +This command can only be executed when the InfluxDB server (`influxd`) is not running. +{{% /note %}} + +## Usage +```sh +influxd recovery user create [flags] +``` + +## Flags +| Flag | | Description | Input Type | +| :--- | :------------ | :------------------------------------------------------------ | :--------: | +| | `--bolt-path` | Path to the BoltDB file (default `~.influxdbv2/influxd.bolt`) | string | +| `-h` | `--help` | Help for `create` | | +| | `--password` | Password for the new user | string | +| | `--username` | Username of the new user | string | + +## Examples + +##### Create a new user directly on disk +```sh +influxd recovery user create \ + --username example-username \ + --password ExAmPL3-paS5W0rD +``` \ No newline at end of file diff --git a/content/influxdb/v2.1/reference/cli/influxd/recovery/user/list.md b/content/influxdb/v2.1/reference/cli/influxd/recovery/user/list.md new file mode 100644 index 0000000000..81e1e6caef --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/recovery/user/list.md @@ -0,0 +1,28 @@ +--- +title: influxd recovery user list +description: > + The `influxd recovery user list` command lists users stored on disk and + outputs data associated with each user. +menu: + influxdb_2_1_ref: + parent: influxd recovery user +weight: 401 +--- + +The `influxd recovery user list` command lists users stored on disk and +outputs data associated with each user. + +{{% note %}} +This command can only be executed when the InfluxDB server (`influxd`) is not running. +{{% /note %}} + +## Usage +```sh +influxd recovery user list [flags] +``` + +## Flags +| Flag | | Description | Input Type | +| :--- | :------------ | :------------------------------------------------------------ | :--------: | +| | `--bolt-path` | Path to the BoltDB file (default `~.influxdbv2/influxd.bolt`) | string | +| `-h` | `--help` | Help for `list` | | \ No newline at end of file diff --git a/content/influxdb/v2.1/reference/cli/influxd/run.md b/content/influxdb/v2.1/reference/cli/influxd/run.md new file mode 100644 index 0000000000..00cc0922d5 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/run.md @@ -0,0 +1,40 @@ +--- +title: influxd run +description: The `influxd run` command is the default `influxd` command and starts the influxd server. +influxdb/v2.1/tags: [influxd, cli] +menu: + influxdb_2_1_ref: + parent: influxd +weight: 201 +related: + - /influxdb/v2.1/reference/config-options/ +products: [oss] +--- + +The `influxd run` command is the default command for `influxd`. +It starts and runs all the processes necessary for InfluxDB to function. + +## Usage + +``` +influxd run [flags] +``` + + +{{% note %}} +Because `run` is the default command for `influxd`, the following commands are the same: + +```bash +influxd +influxd run +``` +{{% /note %}} + +{{% note %}} +For information about other available InfluxDB configuration methods, see +[InfluxDB configuration options](/influxdb/v2.1/reference/config-options/). +{{% /note %}} + +## Flags + +{{% cli/influxd-flags %}} diff --git a/content/influxdb/v2.1/reference/cli/influxd/upgrade.md b/content/influxdb/v2.1/reference/cli/influxd/upgrade.md new file mode 100644 index 0000000000..817f7e4da7 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/upgrade.md @@ -0,0 +1,59 @@ +--- +title: influxd upgrade +description: The `influxd upgrade` command upgrades a InfluxdDB 1.x instance to 2.x. +menu: + influxdb_2_1_ref: + parent: influxd +weight: 201 +products: [oss] +--- + +Use the `influxd upgrade` command to upgrade an instance of InfluxDB 1.x to InfluxDB {{< current-version >}}. +This command copies all data in [databases](/influxdb/v1.8/concepts/glossary/#database) and +[retention policies](/influxdb/v1.8/concepts/glossary/#retention-policy-rp) (used in 1.x) +over to [buckets](/influxdb/v2.1/reference/glossary/#bucket) (used in {{< current-version >}}). + +{{% warn %}} +Be sure to back up all data before upgrading with `influx upgrade`. +{{% /warn %}} + +This command performs the following actions: + +1. Creates the InfluxDB 2.x configuration file using 1.x configuration file options. + Unsupported 1.x options are reported to standard output. + If the configuration file is not available, the 1.x database folder can be passed via th `--v1-dir` flag. +2. Copies and upgrades 1.x database files. + +The target 2.x database directory is specified by the `--engine-path` option. +If changed, the bolt path can be specified by the `--bolt-path` option. + +## Usage + +``` +influxd upgrade [flags] +influxd upgrade [command] +``` + +## Flags + +| Flag | | Description | Input type | +|:-----|:------------------------ |:-----------------------------------------------------------------------------------------------------------|:----------:| +| `-m` | `--bolt-path` | Path for boltdb database (default `~/.influxdbv2/influxd.bolt`) | string | +| `-b` | `--bucket` | Primary bucket name | string | +| | `--config-file` | Custom InfluxDB 1.x config file path (default `~/.influxdb/influxdb.conf`) | string | +| | `--continuous-query-export-path` | Path for exported 1.x continuous queries (default `~/continuous_queries.txt`) | string | +| `-e` | `--engine-path` | Path for persistent engine files (default `~/.influxdbv2/engine`) | string | +| `-f` | `--force` | Skip the confirmation prompt | | +| `-h` | `--help` | Help for `influxd upgrade` | | +| `-c` | `--influx-configs-path` | Path for 2.x `influx` CLI configurations file (default `~/.influxdbv2/configs`) | | +| | `--log-level` | Supported log levels are `debug`, `info`, `warn`, and `error` (default `info`) | string | +| | `--log-path` | Custom log file path (default `~/upgrade.log`) | string | +| `-o` | `--org` | Primary organization name | string | +| | `--overwrite-existing-v2` | Overwrite existing files at the output paths instead of aborting the upgrade process | | +| `-p` | `--password` | Password for username | string | +| `-r` | `--retention` | Duration bucket will retain data (default `0`; retains data infinitely) | string | +| `-t` | `--token` | Token for username. If not specified, a token is auto-generated. | string | +| `-u` | `--username` | Primary username | string | +| | `--v1-dir` | Path to source 1.x `db` directory containing `meta`, `data`, and `wal` sub-folders (default `~/.influxdb`) | string | +| | `--v2-config-path` | Destination path for upgraded 2.x configuration file (default `~/.influxdbv2/config.toml`) | string | +| `-v` | `--verbose` | Verbose output | | diff --git a/content/influxdb/v2.1/reference/cli/influxd/version.md b/content/influxdb/v2.1/reference/cli/influxd/version.md new file mode 100644 index 0000000000..92bef85aa9 --- /dev/null +++ b/content/influxdb/v2.1/reference/cli/influxd/version.md @@ -0,0 +1,24 @@ +--- +title: influxd version +description: The `influxd version` command outputs the current version of InfluxDB. +influxdb/v2.1/tags: [influxd, cli] +menu: + influxdb_2_1_ref: + parent: influxd +weight: 202 +products: [oss] +--- + +The `influxd version` command outputs the current version of InfluxDB. + +## Usage + +``` +influxd version [flags] +``` + +## Flags + +| Flag | | Description | +|:---- |:--- |:----------- | +| `-h` | `--help` | Help for the `version` command | diff --git a/content/influxdb/v2.1/reference/config-options.md b/content/influxdb/v2.1/reference/config-options.md new file mode 100644 index 0000000000..01292e5a0b --- /dev/null +++ b/content/influxdb/v2.1/reference/config-options.md @@ -0,0 +1,3418 @@ +--- +title: InfluxDB configuration options +description: > + Customize your InfluxDB configuration by using [`influxd`](/influxdb/v2.1/reference/cli/influxd/) + configuration flags, setting environment variables, or defining configuration + options in a configuration file. +menu: + influxdb_2_1_ref: + name: Configuration options +weight: 3 +products: [oss] +related: + - /influxdb/v2.1/reference/cli/influxd +--- + +Customize your InfluxDB configuration by using [`influxd`](/influxdb/v2.1/reference/cli/influxd/) +configuration flags, setting environment variables, or defining configuration +options in a configuration file. + +### Configuration precedence +InfluxDB honors configuration settings using the following precedence: + +1. `influxd` flags +2. Environment variables +3. Configuration file settings + +### InfluxDB configuration file +When `influxd` starts, it checks for a file named `config.*` **in the current working directory**. +The file extension depends on the syntax of the configuration file. +InfluxDB configuration files support the following syntaxes: + +- **YAML** (`.yaml`, `.yml`) +- **TOML** (`.toml`) +- **JSON** (`.json`) + +To customize the directory path of the configuration file, set the `INFLUXD_CONFIG_PATH` +environment variable to your custom path. + +```sh +export INFLUXD_CONFIG_PATH=/path/to/custom/config/directory +``` + +On startup, `influxd` will check for a `config.*` in the `INFLUXD_CONFIG_PATH` directory. + +##### Example configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yaml +query-concurrency: 20 +query-queue-size: 15 +secret-store: vault +session-length: 120 +tls-cert: /path/to/influxdb.crt +tls-key: /path/to/influxdb.key +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +query-concurrency = 20 +query-queue-size = 15 +secret-store = "vault" +session-length = 120 +tls-cert = "/path/to/influxdb.crt" +tls-key = "/path/to/influxdb.key" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "query-concurrency": 20, + "query-queue-size": 15, + "secret-store": "vault", + "session-length": 120, + "tls-cert": "/path/to/influxdb.crt", + "tls-key": "/path/to/influxdb.key" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% note %}} +Only non-default settings need to be defined in the configuration file. +{{% /note %}} + +## Configuration options + +To configure InfluxDB, use the following configuration options when starting the +[`influxd` service](/influxdb/v2.1/reference/cli/influxd): + +- [assets-path](#assets-path) +- [bolt-path](#bolt-path) +- [e2e-testing](#e2e-testing) +- [engine-path](#engine-path) +- [feature-flags](#feature-flags) +- [flux-log-enabled](#flux-log-enabled) +- [http-bind-address](#http-bind-address) +- [http-idle-timeout](#http-idle-timeout) +- [http-read-header-timeout](#http-read-header-timeout) +- [http-read-timeout](#http-read-timeout) +- [http-write-timeout](#http-write-timeout) +- [influxql-max-select-buckets](#influxql-max-select-buckets) +- [influxql-max-select-point](#influxql-max-select-point) +- [influxql-max-select-series](#influxql-max-select-series) +- [log-level](#log-level) +- [metrics-disabled](#metrics-disabled) +- [nats-max-payload-bytes](#nats-max-payload-bytes) +- [nats-port](#nats-port) +- [no-tasks](#no-tasks) +- [pprof-disabled](#pprof-disabled) +- [query-concurrency](#query-concurrency) +- [query-initial-memory-bytes](#query-initial-memory-bytes) +- [query-max-memory-bytes](#query-max-memory-bytes) +- [query-memory-bytes](#query-memory-bytes) +- [query-queue-size](#query-queue-size) +- [reporting-disabled](#reporting-disabled) +- [secret-store](#secret-store) +- [session-length](#session-length) +- [session-renew-disabled](#session-renew-disabled) +- [sqlite-path](#sqlite-path) +- [storage-cache-max-memory-size](#storage-cache-max-memory-size) +- [storage-cache-snapshot-memory-size](#storage-cache-snapshot-memory-size) +- [storage-cache-snapshot-write-cold-duration](#storage-cache-snapshot-write-cold-duration) +- [storage-compact-full-write-cold-duration](#storage-compact-full-write-cold-duration) +- [storage-compact-throughput-burst](#storage-compact-throughput-burst) +- [storage-max-concurrent-compactions](#storage-max-concurrent-compactions) +- [storage-max-index-log-file-size](#storage-max-index-log-file-size) +- [storage-no-validate-field-size](#storage-no-validate-field-size) +- [storage-retention-check-interval](#storage-retention-check-interval) +- [storage-series-file-max-concurrent-snapshot-compactions](#storage-series-file-max-concurrent-snapshot-compactions) +- [storage-series-id-set-cache-size](#storage-series-id-set-cache-size) +- [storage-shard-precreator-advance-period](#storage-shard-precreator-advance-period) +- [storage-shard-precreator-check-interval](#storage-shard-precreator-check-interval) +- [storage-tsm-use-madv-willneed](#storage-tsm-use-madv-willneed) +- [storage-validate-keys](#storage-validate-keys) +- [storage-wal-fsync-delay](#storage-wal-fsync-delay) +- [storage-wal-max-concurrent-writes](#storage-wal-max-concurrent-writes) +- [storage-wal-max-write-delay](#storage-wal-max-write-delay) +- [storage-write-timeout](#storage-write-timeout) +- [store](#store) +- [testing-always-allow-setup](#testing-always-allow-setup) +- [tls-cert](#tls-cert) +- [tls-key](#tls-key) +- [tls-min-version](#tls-min-version) +- [tls-strict-ciphers](#tls-strict-ciphers) +- [tracing-type](#tracing-type) +- [ui-disabled](#ui-disabled) +- [vault-addr](#vault-addr) +- [vault-cacert](#vault-cacert) +- [vault-capath](#vault-capath) +- [vault-client-cert](#vault-client-cert) +- [vault-client-key](#vault-client-key) +- [vault-client-timeout](#vault-client-timeout) +- [vault-max-retries](#vault-max-retries) +- [vault-skip-verify](#vault-skip-verify) +- [vault-tls-server-name](#vault-tls-server-name) +- [vault-token](#vault-token) + +--- + +### assets-path +Override the default InfluxDB user interface (UI) assets by serving assets from the specified directory. +_Typically, InfluxData internal use only._ + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--assets-path` | `INFLUXD_ASSETS_PATH` | `assets-path` | + +###### influxd flag +```sh +influxd --assets-path=/path/to/custom/assets-dir +``` + +###### Environment variable +```sh +export INFLUXD_ASSETS_PATH=/path/to/custom/assets-dir +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +assets-path: /path/to/custom/assets-dir +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +assets-path = "/path/to/custom/assets-dir" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "assets-path": "/path/to/custom/assets-dir" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### bolt-path +Path to the [BoltDB](https://github.com/boltdb/bolt) database. +BoltDB is a key value store written in Go. +InfluxDB uses BoltDB to store data including organization and +user information, UI data, REST resources, and other key value data. + +**Default:** `~/.influxdbv2/influxd.bolt` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--bolt-path` | `INFLUXD_BOLT_PATH` | `bolt-path` | + +###### influxd flag +```sh +influxd --bolt-path=~/.influxdbv2/influxd.bolt +``` + +###### Environment variable +```sh +export INFLUXD_BOLT_PATH=~/.influxdbv2/influxd.bolt +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +bolt-path: ~/.influxdbv2/influxd.bolt +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +bolt-path = "~/.influxdbv2/influxd.bolt" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "bolt-path": "~/.influxdbv2/influxd.bolt" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### e2e-testing +Add a `/debug/flush` endpoint to the InfluxDB HTTP API to clear stores. +InfluxData uses this endpoint in end-to-end testing. + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--e2e-testing` | `INFLUXD_E2E_TESTING` | `e2e-testing` | + +###### influxd flag +```sh +influxd --e2e-testing +``` + +###### Environment variable +```sh +export INFLUXD_E2E_TESTING=true +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +e2e-testing: true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +e2e-testing = true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "e2e-testing": true +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### engine-path +Path to persistent storage engine files where InfluxDB stores all +Time-Structure Merge Tree (TSM) data on disk. + +**Default:** `~/.influxdbv2/engine` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--engine-path` | `INFLUXD_ENGINE_PATH` | `engine-path` | + +###### influxd flag +```sh +influxd --engine-path=~/.influxdbv2/engine +``` + +###### Environment variable +```sh +export INFLUXD_ENGINE_PATH=~/.influxdbv2/engine +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +engine-path: ~/.influxdbv2/engine +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +engine-path = "~/.influxdbv2/engine" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "engine-path": "~/.influxdbv2/engine" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### feature-flags +Enable, disable, or override default values for feature flags. + +{{% note %}} +Feature flags are used to develop and test experimental features and are +intended for internal use only. +{{% /note %}} + +| influxd flag | Environment variable | Configuration key | +| :---------------- | :---------------------- | :---------------- | +| `--feature-flags` | `INFLUXD_FEATURE_FLAGS` | `feature-flags` | + +###### influxd flag +```sh +influxd --feature-flags flag1=value2,flag2=value2 +``` + +###### Environment variable +```sh +export INFLUXD_FEATURE_FLAGS="{\"flag1\":\value1\",\"flag2\":\"value2\"}" +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +feature-flags: + flag1: "value1" + flag2: "value2" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +[feature-flags] + flag1 = "value1" + glag2 = "value2" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "feature-flags": { + "flag1": "value1", + "flag2": "value2" + } +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### flux-log-enabled + +Include option to show detailed logs for Flux queries, including the following log fields: + +- `compiler_type`: Compiler used for processing the query (will always be Flux). +- `response_size`: Size of the response, in bytes. +- `query`: The textual representation of the query. +- `err`: Errors encountered while processing the query. +- `stat_total_duration`: Total duration to process the query. +- `stat_compile_duration`: Duration to compile the query. +- `stat_execute_duration`: Duration to execute the query. +- `stat_max_allocated`: Maximum amount of memory allocated while processing the query, in - bytes. +- `stat_total_allocated`: Total amount of memory allocated while processing the query, in bytes. This includes memory that was freed and then used again. + +**Default:** `false` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--flux-log-enabled` | `INFLUXD_FLUX_LOG_ENABLED` | `flux-log-enabled`| + +###### influxd flag +```sh +influxd --flux-log-enabled=true +``` + +###### Environment variable +```sh +export INFLUXD_FLUX_LOG_ENABLED=true +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +flux-log-enabled: true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +flux-log-enabled = "true" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "flux-log-enabled": "true" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### http-bind-address +Bind address for the InfluxDB HTTP API. +Customize the URL and port for the InfluxDB API and UI. + +**Default:** `:8086` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--http-bind-address` | `INFLUXD_HTTP_BIND_ADDRESS` | `http-bind-address` | + +###### influxd flag +```sh +influxd --http-bind-address=:8086 +``` + +###### Environment variable +```sh +export INFLUXD_HTTP_BIND_ADDRESS=:8086 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +http-bind-address: ":8086" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +http-bind-address = ":8086" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "http-bind-address": ":8086" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### http-idle-timeout +Maximum duration the server should keep established connections alive while waiting for new requests. +Set to `0` for no timeout. + +**Default:** `3m0s` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--http-idle-timeout` | `INFLUXD_HTTP_IDLE_TIMEOUT` | `http-idle-timeout` | + +###### influxd flag +```sh +influxd --http-idle-timeout=3m0s +``` + +###### Environment variable +```sh +export INFLUXD_HTTP_IDLE_TIMEOUT=3m0s +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +http-idle-timeout: 3m0s +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +http-idle-timeout = "3m0s" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "http-idle-timeout": "3m0s" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### http-read-header-timeout +Maximum duration the server should try to read HTTP headers for new requests. +Set to `0` for no timeout. + +**Default:** `10s` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--http-read-header-timeout` | `INFLUXD_HTTP_READ_HEADER_TIMEOUT` | `http-read-header-timeout` | + +###### influxd flag +```sh +influxd --http-read-header-timeout=10s +``` + +###### Environment variable +```sh +export INFLUXD_HTTP_READ_HEADER_TIMEOUT=10s +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +http-read-header-timeout: 10s +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +http-read-header-timeout = "10s" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "http-read-header-timeout": "10s" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### http-read-timeout +Maximum duration the server should try to read the entirety of new requests. +Set to `0` for no timeout. + +**Default:** `0` + +{{% note %}} +#### Set timeouts specific to your workload +Although no `http-read-timeout` is set by default, we **strongly recommend** +setting a timeout specific to your workload. +HTTP timeouts protect against large amounts of open connections that could +potentially hurt performance. +{{% /note %}} + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--http-read-timeout` | `INFLUXD_HTTP_READ_TIMEOUT` | `http-read-timeout` | + +###### influxd flag +```sh +influxd --http-read-timeout=10s +``` + +###### Environment variable +```sh +export INFLUXD_HTTP_READ_TIMEOUT=10s +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +http-read-timeout: 10s +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +http-read-timeout = "10s" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "http-read-timeout": "10s" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### http-write-timeout +Maximum duration the server should spend processing and responding to write requests. +Set to `0` for no timeout. + +**Default:** `0` + +{{% note %}} +#### Set timeouts specific to your workload +Although no `http-write-timeout` is set by default, we **strongly recommend** +setting a timeout specific to your workload. +HTTP timeouts protect against large amounts of open connections that could +potentially hurt performance. +{{% /note %}} + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--http-write-timeout` | `INFLUXD_HTTP_WRITE_TIMEOUT` | `http-write-timeout` | + +###### influxd flag +```sh +influxd --http-write-timeout=10s +``` + +###### Environment variable +```sh +export INFLUXD_HTTP_WRITE_TIMEOUT=10s +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +http-write-timeout: 10s +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +http-write-timeout = "10s" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "http-write-timeout": "10s" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### influxql-max-select-buckets +Maximum number of group by time buckets a `SELECT` statement can create. +`0` allows an unlimited number of buckets. + +**Default:** `0` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--influxql-max-select-buckets` | `INFLUXD_INFLUXQL_MAX_SELECT_BUCKETS` | `influxql-max-select-buckets` | + +###### influxd flag +```sh +influxd --influxql-max-select-buckets=0 +``` + +###### Environment variable +```sh +export INFLUXD_INFLUXQL_MAX_SELECT_BUCKETS=0 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +influxql-max-select-buckets: 0 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +influxql-max-select-buckets = 0 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "influxql-max-select-buckets": 0 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### influxql-max-select-point +Maximum number of points a `SELECT` statement can process. +`0` allows an unlimited number of points. +InfluxDB checks the point count every second (so queries exceeding the maximum aren’t immediately aborted). + +**Default:** `0` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--influxql-max-select-point` | `INFLUXD_INFLUXQL_MAX_SELECT_POINT` | `influxql-max-select-point` | + +###### influxd flag +```sh +influxd --influxql-max-select-point=0 +``` + +###### Environment variable +```sh +export INFLUXD_INFLUXQL_MAX_SELECT_POINT=0 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +influxql-max-select-point: 0 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +influxql-max-select-point = 0 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "influxql-max-select-point": 0 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### influxql-max-select-series +Maximum number of series a `SELECT` statement can return. +`0` allows an unlimited number of series. + +**Default:** `0` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--influxql-max-select-series` | `INFLUXD_INFLUXQL_MAX_SELECT_SERIES` | `influxql-max-select-series` | + +###### influxd flag +```sh +influxd --influxql-max-select-series=0 +``` + +###### Environment variable +```sh +export INFLUXD_INFLUXQL_MAX_SELECT_SERIES=0 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +influxql-max-select-series: 0 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +influxql-max-select-series = 0 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "influxql-max-select-series": 0 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### log-level +Log output level. +InfluxDB outputs log entries with severity levels greater than or equal to the level specified. + +**Options:** `debug`, `info`, `error` +**Default:** `info` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--log-level` | `INFLUXD_LOG_LEVEL` | `log-level` | + +###### influxd flag +```sh +influxd --log-level=info +``` + +###### Environment variable +```sh +export INFLUXD_LOG_LEVEL=info +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +log-level: info +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +log-level = "info" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "log-level": "info" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### metrics-disabled +Disable the HTTP `/metrics` endpoint which exposes internal InfluxDB metrics. + +**Default:** `false` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--metrics-disabled` | `INFLUXD_METRICS_DISABLED` | `metrics-disabled` | + +###### influxd flag +```sh +influxd --metrics-disabled +``` + +###### Environment variable +```sh +export INFLUXD_METRICS_DISABLED=true +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +metrics-disabled: true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +metrics-disabled = true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "metrics-disabled": true +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### nats-max-payload-bytes +Maximum number of bytes allowed in a NATS message payload. + +**Default:** `1048576` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--nats-max-payload-bytes` | `INFLUXD_NATS_MAX_PAYLOAD_BYTES` | `nats-max-payload-bytes` | + +###### influxd flag +```sh +influxd --nats-max-payload-bytes=1048576 +``` + +###### Environment variable +```sh +export INFLUXD_NATS_MAX_PAYLOAD_BYTES=1048576 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +nats-max-payload-bytes: 1048576 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +nats-max-payload-bytes = 1048576 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "nats-max-payload-bytes": 1048576 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### nats-port +Port for the NATS streaming server. `-1` selects a random port. + +**Default:** `-1` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--nats-port` | `INFLUXD_NATS_PORT` | `nats-port` | + +###### influxd flag +```sh +influxd --nats-port=-1 +``` + +###### Environment variable +```sh +export INFLUXD_NATS_PORT=-1 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +nats-port: -1 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +nats-port = -1 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "nats-port": -1 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### no-tasks +Disable the task scheduler. +If problematic tasks prevent InfluxDB from starting, use this option to start +InfluxDB without scheduling or executing tasks. + +**Default:** `false` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--no-tasks` | `INFLUXD_NO_TASKS` | `no-tasks` | + +###### influxd flag +```sh +influxd --no-tasks +``` + +###### Environment variable +```sh +export INFLUXD_NO_TASKS=true +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +no-tasks: true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +no-tasks = true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "no-tasks": true +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### pprof-disabled +Disable the `/debug/pprof` HTTP endpoint. +This endpoint provides runtime profiling data and can be helpful when debugging. + +**Default:** `false` + +| influxd flag | Environment variable | Configuration key | +|:-------------------|:-------------------------|:------------------| +| `--pprof-disabled` | `INFLUXD_PPROF_DISABLED` | `pprof-disabled` | + +###### influxd flag +```sh +influxd --pprof-disabled +``` + +###### Environment variable +```sh +export INFLUXD_PPROF_DISABLED=true +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +pprof-disabled: true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +pprof-disabled = true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "pprof-disabled": true +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### query-concurrency +Number of queries allowed to execute concurrently. + +**Default:** `10` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--query-concurrency` | `INFLUXD_QUERY_CONCURRENCY` | `query-concurrency` | + +###### influxd flag +```sh +influxd --query-concurrency=10 +``` + +###### Environment variable +```sh +export INFLUXD_QUERY_CONCURRENCY=10 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +query-concurrency: 10 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +query-concurrency = 10 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "query-concurrency": 10 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### query-initial-memory-bytes +Initial bytes of memory allocated for a query. + +**Default:** _equal to_ [query-memory-bytes](#query-memory-bytes) + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--query-initial-memory-bytes` | `INFLUXD_QUERY_INITIAL_MEMORY_BYTES` | `query-initial-memory-bytes` | + +###### influxd flag +```sh +influxd --query-initial-memory-bytes=10485760 +``` + +###### Environment variable +```sh +export INFLUXD_QUERY_INITIAL_MEMORY_BYTES=10485760 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +query-initial-memory-bytes: 10485760 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +query-initial-memory-bytes = 10485760 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "query-initial-memory-bytes": 10485760 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### query-max-memory-bytes +Maximum total bytes of memory allowed for queries. + +**Default:** _equal to_ [query-concurrency](#query-concurrency) × [query-memory-bytes](#query-memory-bytes) + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--query-max-memory-bytes` | `INFLUXD_QUERY_MAX_MEMORY_BYTES` | `query-max-memory-bytes` | + +###### influxd flag +```sh +influxd --query-max-memory-bytes=104857600 +``` + +###### Environment variable +```sh +export INFLUXD_QUERY_MAX_MEMORY_BYTES=104857600 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +query-max-memory-bytes: 104857600 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +query-max-memory-bytes = 104857600 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "query-max-memory-bytes": 104857600 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### query-memory-bytes +Maximum bytes of memory allowed for a single query. + +**Default:** _unlimited_ + +{{% note %}} +Must be greater than or equal to [query-initial-memory-bytes](#query-initial-memory-bytes). +{{% /note %}} + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--query-memory-bytes` | `INFLUXD_QUERY_MEMORY_BYTES` | `query-memory-bytes` | + +###### influxd flag +```sh +influxd --query-memory-bytes=10485760 +``` + +###### Environment variable +```sh +export INFLUXD_QUERY_MEMORY_BYTES=10485760 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +query-memory-bytes: 10485760 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +query-memory-bytes = 10485760 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "query-memory-bytes": 10485760 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### query-queue-size +Maximum number of queries allowed in execution queue. +When queue limit is reached, new queries are rejected. + +**Default:** `10` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--query-queue-size` | `INFLUXD_QUERY_QUEUE_SIZE` | `query-queue-size` | + +###### influxd flag +```sh +influxd --query-queue-size=10 +``` + +###### Environment variable +```sh +export INFLUXD_QUERY_QUEUE_SIZE=10 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +query-queue-size: 10 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +query-queue-size = 10 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "query-queue-size": 10 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### reporting-disabled +Disables sending telemetry data to InfluxData. +The [InfluxData telemetry](https://www.influxdata.com/telemetry) page provides +information about what data is collected and how InfluxData uses it. + +**Default:** `false` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--reporting-disabled` | `INFLUXD_REPORTING_DISABLED` | `reporting-disabled` | + +###### influxd flag +```sh +influxd --reporting-disabled +``` + +###### Environment variable +```sh +export INFLUXD_REPORTING_DISABLED=true +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +reporting-disabled: true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +reporting-disabled = true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "reporting-disabled": true +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### secret-store +Specifies the data store for secrets such as passwords and tokens. +Store secrets in either the InfluxDB [internal BoltDB](#bolt-path) +or in [Vault](https://www.vaultproject.io/). + +**Options:** `bolt`, `vault` +**Default:** `bolt` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--secret-store` | `INFLUXD_SECRET_STORE` | `secret-store` | + +###### influxd flag +```sh +influxd --secret-store=bolt +``` + +###### Environment variable +```sh +export INFLUXD_SECRET_STORE=bolt +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +secret-store: bolt +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +secret-store = "bolt" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "secret-store": "bolt" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### session-length +Specifies the Time to Live (TTL) **in minutes** for newly created user sessions. + +**Default:** `60` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--session-length` | `INFLUXD_SESSION_LENGTH` | `session-length` | + +###### influxd flag +```sh +influxd --session-length=60 +``` + +###### Environment variable +```sh +export INFLUXD_SESSION_LENGTH=60 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +session-length: 60 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +session-length = 60 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "session-length": 60 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### session-renew-disabled +Disables automatically extending a user's session TTL on each request. +By default, every request sets the session's expiration time to five minutes from now. +When disabled, sessions expire after the specified [session length](#session-length) +and the user is redirected to the login page, even if recently active. + +**Default:** `false` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--session-renew-disabled` | `INFLUXD_SESSION_RENEW_DISABLED` | `session-renew-disabled` | + +###### influxd flag +```sh +influxd --session-renew-disabled +``` + +###### Environment variable +```sh +export INFLUXD_SESSION_RENEW_DISABLED=true +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +session-renew-disabled: true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +session-renew-disabled = true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "session-renew-disabled": true +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### sqlite-path + +Path to the SQLite database file. +The SQLite database is used to store metadata for notebooks and annotations. + +**Default:** _`influxd.sqlite` in the same directory as the [bolt-path](#bolt-path)._ + +| influxd flag | Environment variable | Configuration key | +|:----------------|:----------------------|:------------------| +| `--sqlite-path` | `INFLUXD_SQLITE_PATH` | `sqlite-path` | + +###### influxd flag +```sh +influxd --sqlite-path ~/.influxdbv2/influxd.sqlite +``` + +###### Environment variable +```sh +export INFLUXD_SQLITE_PATH=~/.influxdbv2/influxd.sqlite +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +sqlite-path: ~/.influxdbv2/influxd.sqlite +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +sqlite-path = "~/.influxdbv2/influxd.sqlite" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "sqlite-path": "~/.influxdbv2/influxd.sqlite" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-cache-max-memory-size +Maximum size (in bytes) a shard's cache can reach before it starts rejecting writes. + +**Default:** `1073741824` + +| influxd flag | Environment variable | Configuration key | +|:----------------------------------|:----------------------------------------|:--------------------------------| +| `--storage-cache-max-memory-size` | `INFLUXD_STORAGE_CACHE_MAX_MEMORY_SIZE` | `storage-cache-max-memory-size` | + +###### influxd flag +```sh +influxd --storage-cache-max-memory-size=1073741824 +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_CACHE_MAX_MEMORY_SIZE=1073741824 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-cache-max-memory-size: 1073741824 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-cache-max-memory-size = 1073741824 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-cache-max-memory-size": 1073741824 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-cache-snapshot-memory-size +Size (in bytes) at which the storage engine will snapshot the cache +and write it to a TSM file to make more memory available. + +**Default:** `26214400`) + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--storage-cache-snapshot-memory-size` | `INFLUXD_STORAGE_CACHE_SNAPSHOT_MEMORY_SIZE` | `storage-cache-snapshot-memory-size` | + +###### influxd flag +```sh +influxd --storage-cache-snapshot-memory-size=26214400 +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_CACHE_SNAPSHOT_MEMORY_SIZE=26214400 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-cache-snapshot-memory-size: 26214400 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-cache-snapshot-memory-size = 26214400 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-cache-snapshot-memory-size": 26214400 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-cache-snapshot-write-cold-duration +Duration at which the storage engine will snapshot the cache and +write it to a new TSM file if the shard hasn't received writes or deletes. + +**Default:** `10m0s` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--storage-cache-snapshot-write-cold-duration` | `INFLUXD_STORAGE_CACHE_SNAPSHOT_WRITE_COLD_DURATION` | `storage-cache-snapshot-write-cold-duration` | + +###### influxd flag +```sh +influxd --storage-cache-snapshot-write-cold-duration=10m0s +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_CACHE_SNAPSHOT_WRITE_COLD_DURATION=10m0s +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-cache-snapshot-write-cold-duration: 10m0s +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-cache-snapshot-write-cold-duration = "10m0s" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-cache-snapshot-write-cold-duration": "10m0s" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-compact-full-write-cold-duration +Duration at which the storage engine will compact all TSM files in a +shard if it hasn't received writes or deletes. + +**Default:** `4h0m0s` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--storage-compact-full-write-cold-duration` | `INFLUXD_STORAGE_COMPACT_FULL_WRITE_COLD_DURATION` | `storage-compact-full-write-cold-duration` | + +###### influxd flag +```sh +influxd --storage-compact-full-write-cold-duration=4h0m0s +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_COMPACT_FULL_WRITE_COLD_DURATION=4h0m0s +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-compact-full-write-cold-duration: 4h0m0s +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-compact-full-write-cold-duration = "4h0m0s" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-compact-full-write-cold-duration": "4h0m0s" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-compact-throughput-burst +Rate limit (in bytes per second) that TSM compactions can write to disk. + +**Default:** `50331648` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--storage-compact-throughput-burst` | `INFLUXD_STORAGE_COMPACT_THROUGHPUT_BURST` | `storage-compact-throughput-burst` | + +###### influxd flag +```sh +influxd --storage-compact-throughput-burst=50331648 +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_COMPACT_THROUGHPUT_BURST=50331648 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-compact-throughput-burst: 50331648 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-compact-throughput-burst = 50331648 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-compact-throughput-burst": 50331648 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-max-concurrent-compactions +Maximum number of full and level compactions that can run concurrently. +A value of `0` results in 50% of `runtime.GOMAXPROCS(0)` used at runtime. +Any number greater than zero limits compactions to that value. +_This setting does not apply to cache snapshotting._ + +**Default:** `0` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--storage-max-concurrent-compactions` | `INFLUXD_STORAGE_MAX_CONCURRENT_COMPACTIONS` | `storage-max-concurrent-compactions` | + +###### influxd flag +```sh +influxd --storage-max-concurrent-compactions=0 +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_MAX_CONCURRENT_COMPACTIONS=0 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-max-concurrent-compactions: 0 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-max-concurrent-compactions = 0 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-max-concurrent-compactions": 0 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-max-index-log-file-size +Size (in bytes) at which an index write-ahead log (WAL) file will compact into an index file. +Lower sizes will cause log files to be compacted more quickly and result in lower +heap usage at the expense of write throughput. + +**Default:** `1048576` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--storage-max-index-log-file-size` | `INFLUXD_STORAGE_MAX_INDEX_LOG_FILE_SIZE` | `storage-max-index-log-file-size` | + +###### influxd flag +```sh +influxd --storage-max-index-log-file-size=1048576 +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_MAX_INDEX_LOG_FILE_SIZE=1048576 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-max-index-log-file-size: 1048576 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-max-index-log-file-size = 1048576 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-max-index-log-file-size": 1048576 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-no-validate-field-size +Skip field size validation on incoming write requests. + +**Default:** `false` + +| influxd flag | Environment variable | Configuration key | +| :--------------------------------- | :--------------------------------------- | :------------------------------- | +| `--storage-no-validate-field-size` | `INFLUXD_STORAGE_NO_VALIDATE_FIELD_SIZE` | `storage-no-validate-field-size` | + +###### influxd flag +```sh +influxd --storage-no-validate-field-size +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_NO_VALIDATE_FIELD_SIZE=true +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-no-validate-field-size: true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-no-validate-field-size = true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-no-validate-field-size": true +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-retention-check-interval +Interval of retention policy enforcement checks. + +**Default:** `30m0s` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--storage-retention-check-interval` | `INFLUXD_STORAGE_RETENTION_CHECK_INTERVAL` | `storage-retention-check-interval` | + +###### influxd flag +```sh +influxd --storage-retention-check-interval=30m0s +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_MAX_INDEX_LOG_FILE_SIZE=30m0s +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-retention-check-interval: 30m0s +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-retention-check-interval = "30m0s" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-retention-check-interval": "30m0s" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-series-file-max-concurrent-snapshot-compactions +Maximum number of snapshot compactions that can run concurrently across +all series partitions in a database. + +**Default:** `0` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--storage-series-file-max-concurrent-snapshot-compactions` | `INFLUXD_STORAGE_SERIES_FILE_MAX_CONCURRENT_SNAPSHOT_COMPACTIONS` | `storage-series-file-max-concurrent-snapshot-compactions` | + +###### influxd flag +```sh +influxd --storage-series-file-max-concurrent-snapshot-compactions=0 +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_SERIES_FILE_MAX_CONCURRENT_SNAPSHOT_COMPACTIONS=0 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-series-file-max-concurrent-snapshot-compactions: 0 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-series-file-max-concurrent-snapshot-compactions = 0 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-series-file-max-concurrent-snapshot-compactions": 0 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-series-id-set-cache-size +Size of the internal cache used in the TSI index to store +previously calculated series results. +Cached results are returned quickly rather than needing to be recalculated when +a subsequent query with the same tag key/value predicate is executed. +Setting this value to `0` will disable the cache and may decrease query performance. + +**Default:** `100` + +{{% note %}} +This value should only be increased if the set of regularly used tag key/value +predicates across all measurements for a database is larger than 100. +An increase in cache size may lead to an increase in heap usage. +{{% /note %}} + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--storage-series-id-set-cache-size` | `INFLUXD_STORAGE_SERIES_ID_SET_CACHE_SIZE` | `storage-series-id-set-cache-size` | + +###### influxd flag +```sh +influxd --storage-series-id-set-cache-size=100 +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_SERIES_ID_SET_CACHE_SIZE=100 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-series-id-set-cache-size: 100 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-series-id-set-cache-size = 100 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-series-id-set-cache-size": 100 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-shard-precreator-advance-period +The time before a shard group's end-time that the successor shard group is created. + +**Default:** `30m0s` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--storage-shard-precreator-advance-period` | `INFLUXD_STORAGE_SHARD_PRECREATOR_ADVANCE_PERIOD` | `storage-shard-precreator-advance-period` | + +###### influxd flag +```sh +influxd --storage-shard-precreator-advance-period=30m0s +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_SHARD_PRECREATOR_ADVANCE_PERIOD=30m0s +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-shard-precreator-advance-period: 30m0s +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-shard-precreator-advance-period = "30m0s" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-shard-precreator-advance-period": "30m0s" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-shard-precreator-check-interval +Interval of pre-create new shards check. + +**Default:** `10m0s` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--storage-shard-precreator-check-interval` | `INFLUXD_STORAGE_SHARD_PRECREATOR_CHECK_INTERVAL` | `storage-shard-precreator-check-interval` | + +###### influxd flag +```sh +influxd --storage-shard-precreator-check-interval=10m0s +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_SHARD_PRECREATOR_CHECK_INTERVAL=10m0s +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-shard-precreator-check-interval: 10m0s +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-shard-precreator-check-interval = "10m0s" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-shard-precreator-check-interval": "10m0s" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-tsm-use-madv-willneed +Inform the kernel that InfluxDB intends to page in mmap'd sections of TSM files. + +**Default:** `false` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--storage-tsm-use-madv-willneed` | `INFLUXD_STORAGE_TSM_USE_MADV_WILLNEED` | `storage-tsm-use-madv-willneed` | + +###### influxd flag +```sh +influxd --storage-tsm-use-madv-willneed +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_TSM_USE_MADV_WILLNEED=true +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-tsm-use-madv-willneed: true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-tsm-use-madv-willneed = true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-tsm-use-madv-willneed": true +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-validate-keys +Validate incoming writes to ensure keys have only valid unicode characters. + +**Default:** `false` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--storage-validate-keys` | `INFLUXD_STORAGE_VALIDATE_KEYS` | `storage-validate-keys` | + +###### influxd flag +```sh +influxd --storage-validate-keys +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_VALIDATE_KEYS=true +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-validate-keys: true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-validate-keys = true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-validate-keys": true +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-wal-fsync-delay +Duration a write will wait before fsyncing. +A duration greater than `0` batches multiple fsync calls. +This is useful for slower disks or when WAL write contention is present. + +**Default:** `0s` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--storage-wal-fsync-delay` | `INFLUXD_STORAGE_WAL_FSYNC_DELAY` | `storage-wal-fsync-delay` | + +###### influxd flag +```sh +influxd --storage-wal-fsync-delay=0s +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_WAL_FSYNC_DELAY=0s +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-wal-fsync-delay: 0s +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-wal-fsync-delay = "0s" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-wal-fsync-delay": "0s" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-wal-max-concurrent-writes +Maximum number writes to the WAL directory to attempt at the same time. + +**Default:** `0` _(number of processing units available × 2)_ + +| influxd flag | Environment variable | Configuration key | +| :------------------------------------ | :------------------------------------------ | :---------------------------------- | +| `--storage-wal-max-concurrent-writes` | `INFLUXD_STORAGE_WAL_MAX_CONCURRENT_WRITES` | `storage-wal-max-concurrent-writes` | + +###### influxd flag +```sh +influxd --storage-wal-max-concurrent-writes=0 +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_WAL_MAX_CONCURRENT_WRITES=0 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-wal-max-concurrent-writes: 0 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-wal-max-concurrent-writes = 0 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-wal-max-concurrent-writes": 0 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-wal-max-write-delay +Maximum amount of time a write request to the WAL directory will wait when the +the [maximum number of concurrent active writes to the WAL directory](#storage-wal-max-concurrent-writes) +has been met. Set to `0` to disable the timeout. + +**Default:** `10m` + +| influxd flag | Environment variable | Configuration key | +| :------------------------------ | :------------------------------------ | :---------------------------- | +| `--storage-wal-max-write-delay` | `INFLUXD_STORAGE_WAL_MAX_WRITE_DELAY` | `storage-wal-max-write-delay` | + +###### influxd flag +```sh +influxd --storage-wal-max-write-delay=10m +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_WAL_MAX_WRITE_DELAY=10m +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-wal-max-write-delay: 10m +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-wal-max-write-delay = "10m" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-wal-max-write-delay": "10m" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### storage-write-timeout +Maximum amount of time the storage engine will process a write request before timing out. + +**Default:** `10s` + +| influxd flag | Environment variable | Configuration key | +| :------------------------ | :------------------------------ | :---------------------- | +| `--storage-write-timeout` | `INFLUXD_STORAGE_WRITE_TIMEOUT` | `storage-write-timeout` | + +###### influxd flag +```sh +influxd --storage-write-timeout=10s +``` + +###### Environment variable +```sh +export INFLUXD_STORAGE_WRITE_TIMEOUT=10s +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +storage-write-timeout: 10s +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +storage-write-timeout = "10s" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "storage-write-timeout": "10s" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### store +Specifies the data store for REST resources. + +**Options:** `disk`, `memory` +**Default:** `disk` + +{{% note %}} +For backwards compatibility, this flag also acceptss `bolt` as a value. +When using `disk`, REST resources are stored on disk using the [bolt-path](#bolt-path) and [sqlite-path](#sqlite-path). +{{% /note %}} + +{{% note %}} +`memory` is meant for transient environments, such as testing environments, where +data persistence does not matter. +InfluxData does not recommend using `memory` in production. +{{% /note %}} + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--store` | `INFLUXD_STORE` | `store` | + +###### influxd flag +```sh +influxd --store=bolt +``` + +###### Environment variable +```sh +export INFLUXD_STORE=bolt +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +store: bolt +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +store = "bolt" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "store": "bolt" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### testing-always-allow-setup +Ensures the `/api/v2/setup` endpoint always returns `true` to allow onboarding. +This configuration option is primary used in continuous integration tests. + +**Default:** `false` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--testing-always-allow-setup` | `INFLUXD_TESTING_ALWAYS_ALLOW_SETUP` | `testing-always-allow-setup` | + +###### influxd flag +```sh +influxd --testing-always-allow-setup +``` + +###### Environment variable +```sh +export INFLUXD_TESTING_ALWAYS_ALLOW_SETUP=true +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +testing-always-allow-setup: true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +testing-always-allow-setup = true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "testing-always-allow-setup": true +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### tls-cert +Path to TLS certificate file. +Requires the [`tls-key`](#tls-key) to be set. + +_For more information, see [Enable TLS encryption](/influxdb/v2.1/security/enable-tls/)._ + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--tls-cert` | `INFLUXD_TLS_CERT` | `tls-cert` | + +###### influxd flag +```sh +influxd --tls-cert=/path/to/influxdb.crt +``` + +###### Environment variable +```sh +export INFLUXD_TLS_CERT=/path/to/influxdb.crt +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +tls-cert: /path/to/influxdb.crt +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +tls-cert = "/path/to/influxdb.crt" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "tls-cert": "/path/to/influxdb.crt" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### tls-key +Path to TLS key file. +Requires the [`tls-cert`](#tls-cert) to be set. + +_For more information, see [Enable TLS encryption](/influxdb/v2.1/security/enable-tls/)._ + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--tls-key` | `INFLUXD_TLS_KEY` | `tls-key` | + +###### influxd flag +```sh +influxd --tls-key=/path/to/influxdb.key +``` + +###### Environment variable +```sh +export INFLUXD_TLS_KEY=/path/to/influxdb.key +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +tls-key: /path/to/influxdb.key +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +tls-key = "/path/to/influxdb.key" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "tls-key": "/path/to/influxdb.key" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### tls-min-version +Minimum accepted TLS version. + +**Default:** `1.2` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--tls-min-version` | `INFLUXD_TLS_MIN_VERSION` | `tls-min-version` | + +###### influxd flag +```sh +influxd --tls-min-version=1.2 +``` + +###### Environment variable +```sh +export INFLUXD_TLS_MIN_VERSION=1.2 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +tls-min-version: "1.2" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +tls-min-version = "1.2" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "tls-min-version": "1.2" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### tls-strict-ciphers +Restrict accepted TLS ciphers to: + +- ECDHE_RSA_WITH_AES_256_GCM_SHA384 +- ECDHE_RSA_WITH_AES_256_CBC_SHA +- RSA_WITH_AES_256_GCM_SHA384 +- RSA_WITH_AES_256_CBC_SHA + +**Default:** `false` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--tls-strict-ciphers` | `INFLUXD_TLS_STRICT_CIPHERS` | `tls-strict-ciphers` | + +###### influxd flag +```sh +influxd --tls-strict-ciphers +``` + +###### Environment variable +```sh +export INFLUXD_TLS_STRICT_CIPHERS=true +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +tls-strict-ciphers: true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +tls-strict-ciphers = true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "tls-strict-ciphers": true +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### tracing-type +Enable tracing in InfluxDB and specifies the tracing type. +Tracing is disabled by default. + +**Options:** `log`, `jaeger` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--tracing-type` | `INFLUXD_TRACING_TYPE` | `tracing-type` | + +###### influxd flag +```sh +influxd --tracing-type=log +``` + +###### Environment variable +```sh +export INFLUXD_TRACING_TYPE=log +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +tracing-type: log +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +tracing-type = "log" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "tracing-type": "log" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### ui-disabled +Disable the InfluxDB user interface (UI). +The UI is enabled by default. + +**Default:** `false` + +| influxd flag | Environment variable | Configuration key | +| :-------------- | :-------------------- | :---------------- | +| `--ui-disabled` | `INFLUXD_UI_DISABLED` | `ui-disabled` | + +###### influxd flag +```sh +influxd --ui-disabled +``` + +###### Environment variable +```sh +export INFLUXD_UI_DISABLED=true +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +ui-disabled: true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +ui-disabled = true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "ui-disabled": true +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### vault-addr +Specifies the address of the Vault server expressed as a URL and port. +For example: `https://127.0.0.1:8200/`. + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--vault-addr` | `VAULT_ADDR` | `vault-addr` | + +###### influxd flag +```sh +influxd --vault-addr=https://127.0.0.1:8200/ +``` + +###### Environment variable +```sh +export VAULT_ADDR=https://127.0.0.1:8200/ +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +vault-addr: https://127.0.0.1:8200/ +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +vault-addr = "https://127.0.0.1:8200/" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "vault-addr": "https://127.0.0.1:8200/" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### vault-cacert +Specifies the path to a PEM-encoded CA certificate file on the local disk. +This file is used to verify the Vault server's SSL certificate. +**This setting takes precedence over the [`--vault-capath`](#vault-capath) setting.** + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--vault-cacert` | `VAULT_CACERT` | `vault-cacert` | + +###### influxd flag +```sh +influxd --vault-cacert=/path/to/ca.pem +``` + +###### Environment variable +```sh +export VAULT_CACERT=/path/to/ca.pem +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +vault-cacert: /path/to/ca.pem +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +vault-cacert = "/path/to/ca.pem" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "vault-cacert": "/path/to/ca.pem" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### vault-capath +Specifies the path to a directory of PEM-encoded CA certificate files on the local disk. +These certificates are used to verify the Vault server's SSL certificate. + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--vault-capath` | `VAULT_CAPATH` | `vault-capath` | + +###### influxd flag +```sh +influxd --vault-capath=/path/to/certs/ +``` + +###### Environment variable +```sh +export VAULT_CAPATH=/path/to/certs/ +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +vault-capath: /path/to/certs/ +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +vault-capath = "/path/to/certs/" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "vault-capath": "/path/to/certs/" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### vault-client-cert +Specifies the path to a PEM-encoded client certificate on the local disk. +This file is used for TLS communication with the Vault server. + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--vault-client-cert` | `VAULT_CLIENT_CERT` | `vault-client-cert` | + +###### influxd flag +```sh +influxd --vault-client-cert=/path/to/client_cert.pem +``` + +###### Environment variable +```sh +export VAULT_CLIENT_CERT=/path/to/client_cert.pem +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +vault-client-cert: /path/to/client_cert.pem +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +vault-client-cert = "/path/to/client_cert.pem" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "vault-client-cert": "/path/to/client_cert.pem" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### vault-client-key +Specifies the path to an unencrypted, PEM-encoded private key on disk which +corresponds to the matching client certificate. + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--vault-client-key` | `VAULT_CLIENT_KEY` | `vault-client-key` | + +###### influxd flag +```sh +influxd --vault-client-key=/path/to/private_key.pem +``` + +###### Environment variable +```sh +export VAULT_CLIENT_KEY=/path/to/private_key.pem +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +vault-client-key: /path/to/private_key.pem +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +vault-client-key = "/path/to/private_key.pem" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "vault-client-key": "/path/to/private_key.pem" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### vault-max-retries +Specifies the maximum number of retries when encountering a 5xx error code. +The default is 2 (for three attempts in total). Set this to 0 or less to disable retrying. + +**Default:** `2` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--vault-max-retries` | `VAULT_MAX_RETRIES` | `vault-max-retries` | + +###### influxd flag +```sh +influxd --vault-max-retries=2 +``` + +###### Environment variable +```sh +export VAULT_MAX_RETRIES=2 +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +vault-max-retries: 2 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +vault-max-retries = 2 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "vault-max-retries": 2 +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### vault-client-timeout +Specifies the Vault client timeout. + +**Default:** `60s` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--vault-client-timeout` | `VAULT_CLIENT_TIMEOUT` | `vault-client-timeout` | + +###### influxd flag +```sh +influxd --vault-client-timeout=60s +``` + +###### Environment variable +```sh +export VAULT_CLIENT_TIMEOUT=60s +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +vault-client-timeout: 60s +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +vault-client-timeout = "60s" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "vault-client-timeout": "60s" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### vault-skip-verify +Skip certificate verification when communicating with Vault. +_Setting this variable voids [Vault's security model](https://www.vaultproject.io/docs/internals/security.html) +and is **not recommended**._ + +**Default:** `false` + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--vault-skip-verify` | `VAULT_SKIP_VERIFY` | `vault-skip-verify` | + +###### influxd flag +```sh +influxd --vault-skip-verify +``` + +###### Environment variable +```sh +export VAULT_SKIP_VERIFY=true +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +vault-skip-verify: true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +vault-skip-verify = true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "vault-skip-verify": true +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### vault-tls-server-name +Specifies the name to use as the Server Name Indication (SNI) host when connecting via TLS. + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--vault-tls-server-name` | `VAULT_TLS_SERVER_NAME` | `vault-tls-server-name` | + +###### influxd flag +```sh +influxd --vault-tls-server-name=secure.example.com +``` + +###### Environment variable +```sh +export VAULT_TLS_SERVER_NAME=secure.example.com +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +vault-tls-server-name: secure.example.com +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +vault-tls-server-name = "secure.example.com" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "vault-tls-server-name": "secure.example.com" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### vault-token +Specifies the Vault token use when authenticating with Vault. + +| influxd flag | Environment variable | Configuration key | +|:------------ |:-------------------- |:----------------- | +| `--vault-token` | `VAULT_TOKEN` | `vault-token` | + +###### influxd flag +```sh +influxd --vault-token=exAmple-t0ken-958a-f490-c7fd0eda5e9e +``` + +###### Environment variable +```sh +export VAULT_TOKEN=exAmple-t0ken-958a-f490-c7fd0eda5e9e +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +vault-token: exAmple-t0ken-958a-f490-c7fd0eda5e9e +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +vault-token = "exAmple-t0ken-958a-f490-c7fd0eda5e9e" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "vault-token": "exAmple-t0ken-958a-f490-c7fd0eda5e9e" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} diff --git a/content/influxdb/v2.1/reference/contributing/_index.md b/content/influxdb/v2.1/reference/contributing/_index.md new file mode 100644 index 0000000000..ed2811c0e5 --- /dev/null +++ b/content/influxdb/v2.1/reference/contributing/_index.md @@ -0,0 +1,26 @@ +--- +title: Contribute to InfluxDB OSS +description: Find important information about what's included in new versions of InfluxData products. +menu: + influxdb_2_1_ref: + name: Contribute to InfluxDB + weight: 10 +--- + +To contribute to the InfluxDB OSS project, complete the following steps: + +1. [Sign the InfluxData Contributor License Agreement (CLA)](#sign-influxdata-contributor-license-agreement-cla). +2. [Review contribution guidelines](#review-contribution-guidelines). +3. [Review the InfluxDB open source license](#review-open-source-license). + +## Sign InfluxData Contributor License Agreement (CLA) + +Before contributing to the InfluxDB OSS project, you must complete and sign the [InfluxData Contributor License Agreement (CLA)](https://www.influxdata.com/legal/cla/), available on the InfluxData website. + +## Review contribution guidelines + +To learn how you can contribute to the InfluxDB OSS project, see our [Contributing guidelines](https://github.com/influxdata/influxdb/blob/master/CONTRIBUTING.md) in the GitHub repository. + +## Review open source license + +See information about our [open source MIT license for InfluxDB](https://github.com/influxdata/influxdb/blob/master/LICENSE) in GitHub. diff --git a/content/influxdb/v2.1/reference/glossary.md b/content/influxdb/v2.1/reference/glossary.md new file mode 100644 index 0000000000..703e8c40b4 --- /dev/null +++ b/content/influxdb/v2.1/reference/glossary.md @@ -0,0 +1,1222 @@ +--- +title: Glossary +description: > + Terms related to InfluxData products and platforms. +weight: 9 +menu: + influxdb_2_1_ref: + name: Glossary +influxdb/v2.1/tags: [glossary] +--- + +[A](#a) | [B](#b) | [C](#c) | [D](#d) | [E](#e) | [F](#f) | [G](#g) | [H](#h) | [I](#i) | [J](#j) | [K](#k) | [L](#l) | [M](#m) | [N](#n) | [O](#o) | [P](#p) | [Q](#q) | [R](#r) | [S](#s) | [T](#t) | [U](#u) | [V](#v) | [W](#w) | X | Y | Z + +## A + +### agent + +A background process started by (or on behalf of) a user and typically requires user input. + +Telegraf is an agent that requires user input (a configuration file) to gather metrics from declared input plugins and sends metrics to declared output plugins, based on the plugins enabled for a configuration. + +Related entries: [input plugin](#input-plugin), [output plugin](#output-plugin), [daemon](#daemon) + +### aggregator plugin + +Receives metrics from input plugins, creates aggregate metrics, and then passes aggregate metrics to configured output plugins. + +Related entries: [input plugin](#input-plugin), [output plugin](#output-plugin), [processor plugin](#processor-plugin) + +### aggregate + +A function that returns an aggregated value across a set of points. +For a list of available aggregation functions, see [Flux aggregate functions](/{{< latest "flux" >}}/function-types#aggregates). + +Related entries: [function](#function), [selector](#selector), [transformation](#transformation) + +## B + +### bar graph + +A visual representation in the InfluxDB user interface used to compare variables (bars) and plot categorical data. +A bar graph has spaces between bars, can be sorted in any order, and bars in the graph typically have the same width. + +Related entries: [histogram](#histogram) + +### batch + +A collection of points in line protocol format, separated by newlines (`0x0A`). +Submitting a batch of points using a single HTTP request to the write endpoints drastically increases performance by reducing the HTTP overhead. +InfluxData typically recommends batch sizes of 5,000-10,000 points. +In some use cases, performance may improve with significantly smaller or larger batches. + +Related entries: [line protocol](/influxdb/v2.1/reference/syntax/line-protocol/), [point](#point) + +### batch size + +The number of lines or individual data points in a line protocol batch. +The Telegraf agent sends metrics to output plugins in batches rather than individually. +Batch size controls the size of each write batch that Telegraf sends to the output plugins. + +Related entries: [output plugin](#output-plugin) + +### bin + +In a cumulative histogram, a bin includes all data points less than or equal to a specified upper bound. +In a normal histogram, a bin includes all data points between the upper and lower bounds. + +### block + +In Flux, a block is a possibly empty sequence of statements within matching braces (`{ }`). +Two types of blocks exist in Flux: + +- Explicit blocks in the source code, for example: + + ``` + Block = "{" StatementList "} + StatementList = { Statement } + ``` + +- Implicit blocks, including: + + - Universe: Encompasses all Flux source text. + - Package: Each package includes a package block that contains Flux source text for the package. + - File: Each file has a file block containing Flux source text in the file. + - Function: Each function literal has a function block with Flux source text (even if not explicitly declared). + +Related entries: [implicit block](#implicit-block), [explicit block](#explicit-block) + +### boolean + +A data type with two possible values: true or false. +By convention, you can express `true` as the integer `1` and false as the integer `0` (zero). +In [annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv/), columns that contain +boolean values are annotated with the `boolean` datatype. + +### bucket + +A bucket is a named location where time series data is stored. +All buckets have a [retention period](#retention-period). +A bucket belongs to an organization. + + +### bucket schema + +In InfluxDB Cloud, an explicit bucket schema lets you strictly enforce the data that can be written into one or more measurements in a bucket by defining the column names, tags, fields, and data types allowed for each measurement. By default, buckets in InfluxDB {{< current-version >}} have an `implicit` schema that lets you write data without restrictions on columns, fields, or data types. + +Learn how to [manage bucket schemas](/influxdb/cloud/organizations/buckets/bucket-schema/) in InfluxDB Cloud. + +Related entries: [data type](#data-type), [field](#field), [measurement](#measurement) + +## C + +### check + +Checks are part of queries used in monitoring to read input data and assign a [status](#check-status) (`_level`) based on specified conditions. +For example: + +``` +monitor.check( + crit: (r) => r._value > 90.0, + warn: (r) => r._value > 80.0, + info: (r) => r._value > 60.0, + ok: (r) => r._value <= 20.0, + messageFn: (r) => "The current level is ${r._level}", +) +``` + +This check gives rows with a `_value` greater than 90.0 a crit `_level`; rows greater than 80.0 get a warn `_level`, and so on. + +Learn how to [create a check](/influxdb/v2.1/monitor-alert/checks/create/). + +Related entries: [check status](#check-status), [notification rule](#notification-rule), [notification endpoint](#notification-endpoint) + +### check status + +A [check](#check) gets one of the following statuses (`_level`): `crit`, `info`, `warn`, or `ok`. +Check statuses are written to a status measurement in the `_monitoring` bucket. + +Related entries: [check](#check), [notification rule](#notification-rule), [notification endpoint](#notification-endpoint) + +### CSV + +Comma-separated values (CSV) delimits text between commas to separate values. +A CSV file stores tabular data (numbers and text) in plain text. +Each line of the file is a data record. +Each record consists of one or more fields, separated by commas. +CSV file format is not fully standardized. + +InfluxData uses annotated CSV (comma-separated values) format to encode HTTP responses and results returned to the Flux csv.from() function. +For more detail, see [Annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv/). + + + +### co-monitoring dashboard + +The prebuilt co-monitoring dashboard displays details of your instance based on metrics from Telegraf, allowing you to monitor overall performance. + +### collect + +Collect and write time series data to InfluxDB using line protocol, Telegraf or InfluxDB scrapers, the InfluxDB v2 API, influx command line interface (CLI),the InfluxDB user interface (UI), and client libraries. + +### collection interval + +The default global interval for collecting data from each Telegraf input plugin. +The collection interval can be overridden by each individual input plugin's configuration. + +Related entries: [input plugin](#input-plugin) + + + +### collection jitter + +Collection jitter prevents every input plugin from collecting metrics simultaneously, which can have a measurable effect on the system. +For each collection interval, every Telegraf input plugin will sleep for a random time between zero and the collection jitter before collecting the metrics. + +Related entries: [collection interval](#collection-interval), [input plugin](#input-plugin) + +### column + +InfluxDB data is stored in tables within rows and columns. +Columns store tag sets (indexed) and fields sets. +The only required column is _time_, which stores timestamps and is included in all InfluxDB tables. + +### comment + +Use comments with Flux statements to describe your functions. + +### common log format (CLF) + +A standardized text file format used by the InfluxDB web server to create log entries when generating server log files. + +### compaction + +Compressing time series data to optimize disk usage. + +### continuous query (CQ) + +Continuous queries are the predecessor to tasks in InfluxDB {{< current-version >}}. +Continuous queries run automatically and periodically on a database. + +Related entries: [function](#function) + +## D + +### daemon + +A background process that runs without user input. + +### dashboard + +InfluxDB dashboards visualize time series data. +Use dashboards to query and graph data. + +### dashboard variable + +Dashboard template variables define components of a cell query. +Dashboard variables make is easier to interact with and explore your databoard data. +Use the InfluxDB user interface (UI) to add predefined template variables or customize your own template variables. + +### Data Explorer + +Use the Data Explorer in the InfluxDB user interface (UI) to view, add, or delete variables and functions manually or using the Script Editor. + +### data model + +A data model organizes elements of data and standardizes how they relate to one another and to properties of the real world entities. + +Flux uses a data model built from basic data types: tables, records, columns and streams. + + + +### data service + +Stores time series data and handles writes and queries. + +### data source + +A source of data that InfluxDB collects or queries data from. +Examples include InfluxDB buckets, Prometheus, Postgres, MySQL, and InfluxDB clients. + +Related entries: [bucket](#bucket) + +### data type + +A data type is defined by the values it can take, the programming language used, or the operations that can be performed on it. + +InfluxDB supports the following data types: +| Data type | Alias/annotation | +| :--------------- | :----------------- | +| string | | +| boolean | | +| float | double | +| integer | int, long | +| unsigned integer | uint, unsignedLong | +| time | dateTime | + +For more information about different data types, see: +- [annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv/) +- [extended annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/extended/#datatype) +- [line protocol](/influxdb/v2.1/reference/syntax/line-protocol/#data-types-and-format) +- [InfluxQL](/influxdb/v1.8/query_language/spec/#literals) +- [Flux](/influxdb/v2.1/reference/flux/language/types/) +- [InfluxDB](/influxdb/v2.1/reference/syntax/line-protocol/#data-types-and-format) + +### database + +In InfluxDB {{< current-version >}}, a database represents the InfluxDB instance as a whole. + +Related entries: [continuous query](#continuous-query-cq), [user](#user) + +### date-time + +InfluxDB stores the date-time format for each data point in a timestamp with nanosecond-precision Unix time. +Specifying a timestamp is options. +If a timestamp isn't specified for a data point, InfluxDB uses the server’s local nanosecond timestamp in UTC. + +### downsample + +Aggregating high resolution data into lower resolution data to preserve disk space. + +### duration + +A data type that represents a duration of time (1s, 1m, 1h, 1d). +Retention policies are set using durations. +Data older than the duration is automatically dropped from the database. + + + +## E + +### event + +Metrics gathered at irregular time intervals. + +### explicit block + +In Flux, a an explicit block is a possibly empty sequence of statements within matching braces (`{ }`) that is defined in the source code, for example: + +``` +Block = "{" StatementList "} +StatementList = { Statement } +``` + +Related entries: [implicit block](#implicit-block), [block](#block) + +### expression + +A combination of one or more constants, variables, operators, and functions. + +## F + +### field + +The key-value pair in InfluxDB's data structure that records metadata and the actual data value. +Fields are required in InfluxDB's data structure and they are not indexed - queries on field values scan all points that match the specified time range and, as a result, are not performant relative to tags. + +*Query tip:* Compare fields to tags; tags are indexed. + +Related entries: [field key](#field-key), [field set](#field-set), [field value](#field-value), [tag](#tag) + +### field key + +The key of the key-value pair. +Field keys are strings and they store metadata. + +Related entries: [field](#field), [field set](#field-set), [field value](#field-value), [tag key](#tag-key) + +### field set + +The collection of field keys and field values on a point. + +Related entries: [field](#field), [field key](#field-key), [field value](#field-value), [point](#point) + +### field value + +The value of a key-value pair. +Field values are the actual data; they can be strings, floats, integers, or booleans. +A field value is always associated with a timestamp. + +Field values are not indexed - queries on field values scan all points that match the specified time range and, as a result, are not performant. + +*Query tip:* Compare field values to tag values; tag values are indexed. + +Related entries: [field](#field), [field key](#field-key), [field set](#field-set), [tag value](#tag-value), [timestamp](#timestamp) + +### file block + +A file block is a fixed-length chunk of data read into memory when requested by an application. + +Related entries: [block](#block) + +### float + +A real number written with a decimal point dividing the integer and fractional parts (`1.0`, `3.14`, `-20.1`). +InfluxDB supports 64-bit float values. +In [annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv/), columns that contain +float values are annotated with the `double` datatype. + +### flush interval + +The global interval for flushing data from each Telegraf output plugin to its destination. +This value should not be set lower than the collection interval. + +Related entries: [collection interval](#collection-interval), [flush jitter](#flush-jitter), [output plugin](#output-plugin) + +### flush jitter + +Flush jitter prevents every Telegraf output plugin from sending writes simultaneously, which can overwhelm some data sinks. +Each flush interval, every Telegraf output plugin will sleep for a random time between zero and the flush jitter before emitting metrics. +Flush jitter smooths out write spikes when running a large number of Telegraf instances. + +Related entries: [flush interval](#flush-interval), [output plugin](#output-plugin) + +### Flux + +A lightweight scripting language for querying databases (like InfluxDB) and working with data. + +### function + +Flux functions aggregate, select, and transform time series data. +For a complete list of Flux functions, see [Flux functions](/{{< latest "flux" >}}/stdlib/all-functions/). + +Related entries: [aggregate](#aggregate), [selector](#selector), [transformation](#transformation) + +### function block + +In Flux, each file has a file block containing all Flux source text in that file. +Each function literal has its own function block even if not explicitly declared. + +## G + +### gauge + + A type of visualization that displays the single most recent value for a time series. +A gauge typically displays one or more measures from a single row, and is not designed to display multiple rows of data. +Elements include a range, major and minor tick marks (within the range), and a pointer (needle) indicating the single most recent value. + +### graph + +A diagram that visually depicts the relation between variable quantities measured along specified axes. + +### group key +Group keys determine the schema and contents of tables in Flux output. +A group key is a list of columns for which every row in the table has the same value. +Columns with unique values in each row are not part of the group key. + +### gzip + +gzip is a type of data compression that compress chunks of data, which is restored by unzipping compressed gzip files. +The gzip file extension is `.gz`. + +## H + + + +### histogram + +A visual representation of statistical information that uses rectangles to show the frequency of data items in successive, equal intervals or bins. + +## I + +### identifier + +Identifiers are tokens that refer to task names, bucket names, field keys, +measurement names, tag keys, and user names. +For examples and rules, see [Flux language lexical elements](/{{< latest "flux" >}}/spec/lexical-elements/#identifiers). + +Related entries: +[bucket](#bucket) +[field key](#field-key), +[measurement](#measurement), + +[tag key](#tag-key), +[user](#user) + +### implicit block + +In Flux, an implicit block is a possibly empty sequence of statements within matching braces ({ }) that includes the following types: + + - Universe: Encompasses all Flux source text. + - Package: Each package includes a package block that contains Flux source text for the package. + - File: Each file has a file block containing Flux source text in the file. + - Function: Each function literal has a function block with Flux source text (even if not explicitly declared). + +Related entries: [explict block](#explicit-block), [block](#block) + +### influx + +`influx` is a command line interface (CLI) that interacts with the InfluxDB daemon (influxd). + +### influxd + +`influxd` is the InfluxDB daemon that runs the InfluxDB server and other required processes. + +### InfluxDB + +An open-source time series database (TSDB) developed by InfluxData. +Written in Go and optimized for fast, high-availability storage and retrieval of time series data in fields such as operations monitoring, application metrics, Internet of Things sensor data, and real-time analytics. + +### InfluxDB UI + +The graphical web interface provided by InfluxDB for visualizing data and managing InfluxDB functionality. + +### InfluxQL + +The SQL-like query language used to query data in InfluxDB 1.x. +The prefered method for querying data in InfluxDB {{< current-version >}} is the [Flux](#flux) language. + +### input plugin + +Telegraf input plugins actively gather metrics and deliver them to the core agent, where aggregator, processor, and output plugins can operate on the metrics. +In order to activate an input plugin, it needs to be enabled and configured in Telegraf's configuration file. + +Related entries: [aggregator plugin](#aggregator-plugin), [collection interval](#collection-interval), [output plugin](#output-plugin), [processor plugin](#processor-plugin) + +### instance + +An entity comprising data on a server (or virtual server in cloud computing). + + +### integer + +A whole number that is positive, negative, or zero (`0`, `-5`, `143`). +InfluxDB supports 64-bit integers (minimum: `-9223372036854775808`, maximum: `9223372036854775807`). +In [annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv/), columns that contain +integers are annotated with the `long` datatype. + +Related entries: [unsigned integer](#unsigned-integer) + +## J + +### JWT + +Typically, JSON web tokens (JWT) are used to authenticate users between an identity provider and a service provider. +A server can generate a JWT to assert any business processes. +For example, an "admin" token sent to a client can prove the client is logged in as admin. +Tokens are signed by one party's private key (typically, the server). +Private keys are used by both parties to verify that a token is legitimate. + +JWT uses an open standard specified in [RFC 7519](https://tools.ietf.org/html/rfc7519). + +### Jaeger + +Open source tracing used in distributed systems to monitor and troubleshoot transactions. + +### JSON + +JavaScript Object Notation (JSON) is an open-standard file format that uses human-readable text to transmit data objects consisting of attribute–value pairs and array data types. + +## K + +### keyword + +A keyword is reserved by a program because it has special meaning. +Every programming language has a set of keywords (reserved names) that cannot be used as an identifier. + +See a list of [Flux keywords](/{{< latest "flux" >}}/spec/lexical-elements/#keywords). + +## L + +### literal + +A literal is value in an expression, a number, character, string, function, record, or array. +Literal values are interpreted as defined. + +See examples of [Flux literals](/{{< latest "flux" >}}/spec/expressions/#examples-of-function-literals). + + + +### logs + +Logs record information. +Event logs describe system events and activity that help to describe and diagnose problems. +Transaction logs describe changes to stored data that help recover data if a database crashes or other errors occur. + +The InfluxDB {{< current-version >}} user interface (UI) can be used to view log history and data. + +### Line protocol (LP) + +The text based format for writing points to InfluxDB. +See [line protocol](/influxdb/v2.1/reference/syntax/line-protocol/). + +## M + +### measurement + +The part of InfluxDB's structure that describes the data stored in the associated fields. +Measurements are strings. + +Related entries: [field](#field), [series](#series) + +### member + +A user in an organization. + + + + +### metric + +Data tracked over time. + +### metric buffer + +The metric buffer caches individual metrics when writes are failing for an Telegraf output plugin. +Telegraf will attempt to flush the buffer upon a successful write to the output. +The oldest metrics are dropped first when this buffer fills. + +Related entries: [output plugin](#output-plugin) + +### missing values + +Denoted by a null value. +Identifies missing information, which may be useful to include in an error message. + +The Flux data model includes [Missing values (null)](/{{< latest "flux" >}}/spec/data-model/#missing-values-null). + +## N + +### node + +An independent `influxd` process. + +Related entries: [server](#server) + +### notification endpoint + + The notification endpoint specifies the Slack or PagerDuty endpoint to send a notification and contains configuration details for connecting to the endpoint. +Learn how to [create a notification endpoint](/influxdb/v2.1/monitor-alert/notification-endpoints/create). + +Related entries: [check](#check), [notification rule](#notification-rule) + +### notification rule + +A notification rule specifies a status level (and tags) to alert on, the notification message to send for the specified status level (or change in status level), and the interval or schedule you want to check the status level (and tags). +If conditions are met, the notification rule sends a message to the [notification endpoint](#notification-endpoint) and stores a receipt in a notification measurement in the `_monitoring` bucket. +For example, a notification rule may specify a message to send to a Slack endpoint when a status level is critical (`crit`). + +Learn how to [create a notification rule](/influxdb/v2.1/monitor-alert/notification-rules/create). + +Related entries: [check](#check), [notification endpoint](#notification-endpoint) + +### now() + +The local server's nanosecond timestamp. + +### null + +A data type that represents a missing or unknown value. +Denoted by the null value. + +## O + +### operator + +A symbol that usually represents an action or process. +For example: `+`, `-`, `>`. + +### operand + +The object or value on either side of an operator. + +### option + +Represents a storage location for any value of a specified type. +Mutable, can hold different values during its lifetime. + +See built-in Flux [options](/{{< latest "flux" >}}/spec/options/). + +### option assignment + +An option assignment binds an identifier to an option. + +Learn about the [option assignment](/{{< latest "flux" >}}/spec/assignment-scope/#option-assignment) in Flux. + +### organization + +A workspace for a group of users. +All dashboards, tasks, buckets, members, and so on, belong to an organization. + +### output plugin + +Telegraf output plugins deliver metrics to their configured destination. +To activate an output plugin, enable and configure the plugin in Telegraf's configuration file. + +Related entries: [aggregator plugin](#aggregator-plugin), [flush interval](#flush-interval), [input plugin](#input-plugin), [processor plugin](#processor-plugin) + +## P + +### parameter + +A key-value pair used to pass information to functions. + +### pipe + +Method for passing information from one process to another. +For example, an output parameter from one process is input to another process. +Information passed through a pipe is retained until the receiving process reads the information. + +### pipe-forward operator + +An operator (`|>`) used in Flux to chain operations together. +Specifies the output from a function is input to next function. + +### point + +In InfluxDB, a point represents a single data record, similar to a row in a SQL database table. +Each point: + +- has a measurement, a tag set, a field key, a field value, and a timestamp; +- is uniquely identified by its series and timestamp. + +In a series, each point has a unique timestamp. +If you write a point to a series with a timestamp that matches an existing point, the field set becomes a union of the old and new field set, where any ties go to the new field set. + +Related entries: [measurement](#measurement), [tag set](#tag-set), [field set](#field-set), [timestamp](#timestamp) + +### precision + +The precision configuration setting determines the timestamp precision retained for input data points. +All incoming timestamps are truncated to the specified precision. +Valid precisions are `ns`, `us` or `µs`, `ms`, and `s`. + +In Telegraf, truncated timestamps are padded with zeros to create a nanosecond timestamp. +Telegraf output plugins emit timestamps in nanoseconds. +For example, if the precision is set to `ms`, the nanosecond epoch timestamp `1480000000123456789` is truncated to `1480000000123` in millisecond precision and padded with zeroes to make a new, less precise nanosecond timestamp of `1480000000123000000`. +Telegraf output plugins do not alter the timestamp further. +The precision setting is ignored for service input plugins. + +Related entries: [aggregator plugin](#aggregator-plugin), [input plugin](#input-plugin), [output plugin](#output-plugin), [processor plugin](#processor-plugin), [service input plugin](#service-input-plugin) + +### predicate expression + +A predicate expression compares two values and returns `true` or `false` based on +the relationship between the two values. +A predicate expression is comprised of a left operand, a comparison operator, and a right operand. + +### predicate function +A Flux predicate function is an anonymous function that returns `true` or `false` +based on one or more [predicate expressions](#predicate-expression). + +###### Example predicate function +```js +(r) => r.foo == "bar" and r.baz != "quz" +``` + +### process + +A set of predetermined rules. +A process can refer to instructions being executed by the computer processor or refer to the act of manipulating data. + +In Flux, you can process data with [InfluxDB tasks](/influxdb/v2.1/process-data/get-started/). + +### processor plugin + +Telegraf processor plugins transform, decorate, and filter metrics collected by input plugins, passing the transformed metrics to the output plugins. + +Related entries: [aggregator plugin](#aggregator-plugin), [input plugin](#input-plugin), [output plugin](#output-plugin) + +### Prometheus format + +A simple text-based format for exposing metrics and ingesting them into Prometheus or InfluxDB using InfluxDB scrapers. + +Collect data from any accessible endpoint that provides data in the [Prometheus exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/). + +## Q + +### query + +A Flux script that returns time series data, including [tags](#tag) and [timestamps](#timestamp). + +See [Query data in InfluxDB](/influxdb/v2.1/query-data/). + +## R + +### REPL + +A Read-Eval-Print Loop (REPL) is an interactive programming environment where you type a command and immediately see the result. +See [Flux REPL](/influxdb/v2.1/tools/repl/) for information on building and using the REPL. + +### record + +A tuple of named values represented using a record type. + +### regular expressions + +Regular expressions (regex or regexp) are patterns used to match character combinations in strings. + +### retention period +The duration of time that a bucket retains data. +Points with timestamps older than their bucket's retention period are dropped. + +Related entries: [bucket](#bucket), [shard group duration](#shard-group-duration) + + + +### retention policy (RP) +Retention policy is an InfluxDB 1.x concept that represents the duration of time +that each data point in the retention policy persists. +The InfluxDB 2.x equivalent is [retention period](#retention-period). +For more information about retention policies, see the +[latest 1.x documentation](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#retention-policy-rp). + +Related entries: [retention period](#retention-period), + +### RFC3339 timestamp +A timestamp that uses the human readable DateTime format proposed in +[RFC 3339](https://tools.ietf.org/html/rfc3339) (for example: `2020-01-01T00:00:00.00Z`). +Flux and InfluxDB clients return query results with RFC3339 timestamps. + +Related entries: [timestamp](#timestamp), [unix timestamp](#unix-timestamp) + +## S + +### schema + +How data is organized in InfluxDB. +The fundamentals of the InfluxDB schema are buckets (which include retention policies), series, measurements, tag keys, tag values, and field keys. + +Related entries: [bucket](#bucket), [field key](#field-key), [measurement](#measurement), [series](#series), [tag key](#tag-key), [tag value](#tag-value) + +### scrape + +InfluxDB scrapes data from specified targets at regular intervals and writes the data to an InfluxDB bucket. +Data can be scraped from any accessible endpoint that provides data in the [Prometheus exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/). + +### secret +Secrets are key-value pairs that contain information you want to control access to, such as API keys, passwords, or certificates. + +### selector + +A Flux function that returns a single point from the range of specified points. +See [Flux selector functions](/{{< latest "flux" >}}/stdlib/universe/) for a complete list of available selector functions. + +Related entries: [aggregate](#aggregate), [function](#function), [transformation](#transformation) + +### series + +A collection of data in the InfluxDB data structure that shares a measurement, tag set, and bucket. + +Related entries: [field set](#field-set), [measurement](#measurement), [tag set](#tag-set) + +### series cardinality + +The number of unique measurement, tag set, and field key combinations in an InfluxDB bucket. + +For example, assume that an InfluxDB bucket has one measurement. +The single measurement has two tag keys: `email` and `status`. +If there are three different `email`s, and each email address is associated with two +different `status`es, the series cardinality for the measurement is 6 +(3 × 2 = 6): + +| email | status | +| :-------------------- | :----- | +| lorr@influxdata.com | start | +| lorr@influxdata.com | finish | +| marv@influxdata.com | start | +| marv@influxdata.com | finish | +| cliff@influxdata.com | start | +| cliff@influxdata.com | finish | + +In some cases, performing this multiplication may overestimate series cardinality +because of the presence of dependent tags. +Dependent tags are scoped by another tag and do not increase series cardinality. +If we add the tag `firstname` to the example above, the series cardinality +would not be 18 (3 × 2 × 3 = 18). +The series cardinality would remain unchanged at 6, as `firstname` is already scoped by the `email` tag: + +| email | status | firstname | +| :------------------- | :----- | :-------- | +| lorr@influxdata.com | start | lorraine | +| lorr@influxdata.com | finish | lorraine | +| marv@influxdata.com | start | marvin | +| marv@influxdata.com | finish | marvin | +| cliff@influxdata.com | start | clifford | +| cliff@influxdata.com | finish | clifford | + +##### Query for cardinality: +- **Flux:** [influxdb.cardinality()](/{{< latest "flux" >}}/stdlib/influxdb/cardinality/) +- **InfluxQL:** [SHOW CARDINALITY](/{{< latest "influxdb" "v1" >}}/query_language/spec/#show-cardinality) + +Related entries: [field key](#field-key),[measurement](#measurement), [tag key](#tag-key), [tag set](#tag-set) + +### series file + +A file created and used by the **InfluxDB OSS storage engine** +that contains a set of all series keys across the entire database. + +### series key + +A series key identifies a particular series by measurement, tag set, and field key. + +For example: + +``` +# measurement, tag set, field key +h2o_level, location=santa_monica, h2o_feet +``` + +Related entries: [series](#series) + +### server + +A computer, virtual or physical, running InfluxDB. + + +Related entries: [node](#node) + +### service input plugin + +Telegraf input plugins that run in a passive collection mode while the Telegraf agent is running. +Service input plugins listen on a socket for known protocol inputs, or apply their own logic to ingested metrics before delivering metrics to the Telegraf agent. + +Related entries: [aggregator plugin](#aggregator-plugin), [input plugin](#input-plugin), [output plugin](#output-plugin), [processor plugin](#processor-plugin) + +### shard + +A shard contains encoded and compressed data for a specific set of [series](#series). +A shard consists of one or more [TSM files](#tsm-time-structured-merge-tree) on disk. +All points in a series in a given shard group are stored in the same shard (TSM file) on disk. +A shard belongs to a single [shard group](#shard-group). + +For more information, see [Shards and shard groups (OSS)](/influxdb/%762.1/reference/internals/shards/). + +Related entries: [series](#series), [shard duration](#shard-duration), +[shard group](#shard-group), [tsm](#tsm-time-structured-merge-tree) + +### shard group + +Shard groups are logical containers for shards organized by [bucket](#bucket). +Every bucket with data has at least one shard group. +A shard group contains all shards with data for the time interval covered by the shard group. +The interval spanned by each shard group is the [shard group duration](#shard-group-duration). + +For more information, see [Shards and shard groups (OSS)](/influxdb/%762.1/reference/internals/shards/). + +Related entries: [bucket](#bucket), [retention period](#retention-period), +[series](#series), [shard](#shard), [shard duration](#shard-duration) + +### shard group duration + +The duration of time or interval that each [shard group](#shard-group) covers. Set the `shard-group-duration` for each [bucket](#bucket). + +For more information, see: + +- [Shards and shard groups (OSS)](/influxdb/%762.1/reference/internals/shards/) +- [Manage buckets](/influxdb/v2.1/organizations/buckets/) + + + +### Single Stat + +A visualization that displays the numeric value of the most recent point in a table (or series) returned by a query. + +### Snappy compression + +InfluxDB uses snappy compression to compress batches of points. +To improve space and disk IO efficiency, each batch is compressed before being written to disk. + + + +### step-plot + +A data visualization that displays time series data in a staircase graph. +Generate a step-plot using the step [interpolation option for line graphs](/influxdb/v2.1/visualize-data/visualization-types/graph/#options). + +### stream + +Flux processes streams of data. +A stream includes a series of tables over a sequence of time intervals. + +### string + +A data type used to represent text. +In [annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv/), columns that contain +string values are annotated with the `string` datatype. + +## T + +### TCP + +InfluxDB uses Transmission Control Protocol (TCP) port 8086 for client-server communication over the InfluxDB HTTP API. + + + +### table + +Flux processes a series of tables for a specified time series. +These tables in sequence result in a stream of data. + +### tag + +The key-value pair in InfluxDB's data structure that records metadata. +Tags are an optional part of InfluxDB's data structure but they are useful for storing commonly-queried metadata; tags are indexed so queries on tags are performant. +*Query tip:* Compare tags to fields; fields are not indexed. + +Related entries: [field](#field), [tag key](#tag-key), [tag set](#tag-set), [tag value](#tag-value) + +### tag key + +The key of a tag key-value pair. +Tag keys are strings and store metadata. +Tag keys are indexed so queries on tag keys are processed quickly. + +*Query tip:* Compare tag keys to field keys. +Field keys are not indexed. + +Related entries: [field key](#field-key), [tag](#tag), [tag set](#tag-set), [tag value](#tag-value) + +### tag set + +The collection of tag keys and tag values on a point. + +Related entries: [point](#point), [series](#series), [tag](#tag), [tag key](#tag-key), [tag value](#tag-value) + +### tag value + +The value of a tag key-value pair. +Tag values are strings and they store metadata. +Tag values are indexed so queries on tag values are processed quickly. + +Related entries: [tag](#tag), [tag key](#tag-key), [tag set](#tag-set) + +### task + +A scheduled Flux query that runs periodically and may store results in a specified measurement. +Examples include downsampling and batch jobs. +For more information, see [Process Data with InfluxDB tasks](/influxdb/v2.1/process-data/). + +Related entries: [function](#function) + +### Telegraf + +A plugin-driven agent that collects, processes, aggregates, and writes metrics. + +Related entries: [Automatically configure Telegraf](/influxdb/v2.1/write-data/no-code/use-telegraf/auto-config/), [Manually configure Telegraf](/influxdb/v2.1/write-data/no-code/use-telegraf/manual-config/), [Telegraf plugins](/{{< latest "telegraf" >}}/plugins//), [Use Telegraf to collect data](/influxdb/v2.1/write-data/no-code/use-telegraf/), [View a Telegraf configuration](/influxdb/v2.1/telegraf-configs/view/) + +### time (data type) + +A data type that represents a single point in time with nanosecond precision. + +### time series data + +Sequence of data points typically consisting of successive measurements made from the same source over a time interval. +Time series data shows how data evolves over time. +On a time series data graph, one of the axes is always time. +Time series data may be regular or irregular. +Regular time series data changes in constant intervals. +Irregular time series data changes at non-constant intervals. + +### timestamp + +The date and time associated with a point. +Time in InfluxDB is in UTC. + +To specify time when writing data, see [Elements of line protocol](/influxdb/v2.1/reference/syntax/line-protocol/#elements-of-line-protocol). +To specify time when querying data, see [Query InfluxDB with Flux](/influxdb/v2.1/query-data/get-started/query-influxdb/#2-specify-a-time-range). + +Related entries: [point](#point), [unix timestamp](#unix-timestamp), [RFC3339 timestamp](#rfc3339-timestamp) + +### token + +Tokens (or API tokens) verify user and organization permissions in InfluxDB. +There are different types of athentication tokens: + +- **Operator token:** grants full read and write access to all resources in **all organizations in InfluxDB OSS 2.x**. + _InfluxDB Cloud does not support Operator tokens._ +- **All-Access token:** grants full read and write access to all resources in an organization. +- **Read/Write token:** grants read or write access to specific resources in an organization. + +Related entries: [Create a token](/influxdb/v2.1/security/tokens/create-token/). + +### tracing + +By default, tracing is disabled in InfluxDB OSS. +To enable tracing or set other InfluxDB OSS configuration options, +see [InfluxDB OSS configuration options](/influxdb/v2%2E0/reference/config-options/). + +### transformation + +An InfluxQL function that returns a value or a set of values calculated from specified points, but does not return an aggregated value across those points. +See [InfluxQL functions](/{{< latest "influxdb" "v1" >}}/query_language/functions/#transformations) for a complete list of the available and upcoming aggregations. + +Related entries: [aggregate](#aggregate), [function](#function), [selector](#selector) + +### TSI (Time Series Index) + +TSI uses the operating system's page cache to pull frequently accessed data into memory and keep infrequently accessed data on disk. + +### TSL + +The Time Series Logs (TSL) extension (`.tsl`) identifies Time Series Index (TSI) log files, generated by the tsi1 engine. + +### TSM (Time Structured Merge tree) + +A data storage format that allows greater compaction and higher write and read throughput than B+ or LSM tree implementations. +For more information, see [Storage engine](/{{< latest "influxdb" "v1" >}}/concepts/storage_engine/). + +Related entries: [TSI](#tsi-time-series-index) + +## U + +### UDP + +User Datagram Protocol is a packet of information. +When a request is made, a UDP packet is sent to the recipient. +The sender doesn't verify the packet is received. +The sender continues to send the next packets. +This means computers can communicate more quickly. +This protocol is used when speed is desirable and error correction is not necessary. + +### universe block + +An implicit block that encompasses all Flux source text in a universe block. + +### unix timestamp + +Counts time since **Unix Epoch (1970-01-01T00:00:00Z UTC)** in specified units ([precision](#precision)). +Specify timestamp precision when [writing data to InfluxDB](/influxdb/v2.1/write-data/). +InfluxDB supports the following unix timestamp precisions: + +| Precision | Description | Example | +|:--------- |:----------- |:------- | +| `ns` | Nanoseconds | `1577836800000000000` | +| `us` | Microseconds | `1577836800000000` | +| `ms` | Milliseconds | `1577836800000` | +| `s` | Seconds | `1577836800` | + +

    The examples above represent 2020-01-01T00:00:00Z UTC.

    + +Related entries: [timestamp](#timestamp), [RFC3339 timestamp](#rfc3339-timestamp) + +### unsigned integer +A whole number that is positive or zero (`0`, `143`). Also known as a "uinteger." +InfluxDB supports 64-bit unsigned integers (minimum: `0`, maximum: `18446744073709551615`). +In [annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv/), columns that contain +integers are annotated with the `unisgnedLong` datatype. + +Related entries: [integer](#integer) + +### user + +InfluxDB users are granted permission to access to InfluxDB. +Users are added as a member of an organization and are given a unique API token. + +## V + +### values per second + +The preferred measurement of the rate at which data are persisted to InfluxDB. +Write speeds are generally quoted in values per second. + +To calculate the values per second rate, multiply the number of points written +per second by the number of values stored per point. +For example, if the points have four fields each, and a batch of 5000 points is +written 10 times per second, the values per second rate is: + +**4 field values per point** × **5000 points per batch** × **10 batches per second** = **200,000 values per second** + + +Related entries: [batch](#batch), [field](#field), [point](#point) + +### variable + +A storage location (identified by a memory address) paired with an associated symbolic name (an identifier). +A variable contains some known or unknown quantity of information referred to as a value. + +### variable assignment + +A statement that sets or updates the value stored in a variable. + +In Flux, the variable assignment creates a variable bound to an identifier and gives it a type and value. +A variable keeps the same type and value for the remainder of its lifetime. +An identifier assigned to a variable in a block cannot be reassigned in the same block. + +## W + + + +### windowing + +Grouping data based on specified time intervals. +For information about how to window in Flux, see [Window and aggregate data with Flux](/influxdb/v2.1/query-data/flux/window-aggregate/). diff --git a/content/influxdb/v2.1/reference/internals/_index.md b/content/influxdb/v2.1/reference/internals/_index.md new file mode 100644 index 0000000000..5def87951a --- /dev/null +++ b/content/influxdb/v2.1/reference/internals/_index.md @@ -0,0 +1,9 @@ +--- +title: InfluxDB internals +menu: + influxdb_2_1_ref: + name: InfluxDB internals +weight: 7 +--- + +{{< children >}} diff --git a/content/influxdb/v2.1/reference/internals/file-system-layout.md b/content/influxdb/v2.1/reference/internals/file-system-layout.md new file mode 100644 index 0000000000..c13ce48f85 --- /dev/null +++ b/content/influxdb/v2.1/reference/internals/file-system-layout.md @@ -0,0 +1,260 @@ +--- +title: InfluxDB file system layout +description: > + The InfluxDB file system layout depends on the operating system, package manager, + or containerization platform used to install InfluxDB. +weight: 102 +menu: + influxdb_2_1_ref: + name: File system layout + parent: InfluxDB internals +influxdb/v2.1/tags: [storage, internals] +--- + +The InfluxDB file system layout depends on the operating system, installation method, +or containerization platform used to install InfluxDB. + +- [InfluxDB file structure](#influxdb-file-structure) +- [File system layout](#file-system-layout) + +## InfluxDB file structure +The InfluxDB file structure includes of the following: + +#### Engine path +Directory path to the [storage engine](/{{< latest "influxdb" >}}/reference/internals/storage-engine/), +where InfluxDB stores time series data, includes the following directories: + +- **data**: stores Time-Structured Merge Tree (TSM) files +- **wal**: stores Write Ahead Log (WAL) files. + +To customize this path, use the [engine-path](/influxdb/v2.1/reference/config-options/#engine-path) +configuration option. + +#### Bolt path +File path to the [Boltdb](https://github.com/boltdb/bolt) database, a file-based +key-value store for non-time series data, such as InfluxDB users, dashboards, tasks, etc. +To customize this path, use the [bolt-path](/influxdb/v2.1/reference/config-options/#bolt-path) +configuration option. + +#### Configs path +File path to [`influx` CLI connection configurations](/influxdb/v2.1/reference/cli/influx/config/) (configs). +To customize this path, use the `--configs-path` flag with `influx` CLI commands. + +#### InfluxDB configuration files +Some operating systems and package managers store a default InfluxDB (`influxd`) configuration file on disk. +For more information about using InfluxDB configuration files, see +[Configuration options](/influxdb/v2.1/reference/config-options/). + +## File system layout +{{< tabs-wrapper >}} +{{% tabs %}} +[macOS](#) +[Linux](#) +[Windows](#) +[Docker](#) +[Kubernetes](#) +{{% /tabs %}} + +{{% tab-content %}} + +#### macOS default paths +| Path | Default | +|:------------------------------|:-------------------------------| +| [Engine path](#engine-path) | `~/.influxdbv2/engine/` | +| [Bolt path](#bolt-path) | `~/.influxdbv2/influxd.bolt` | +| [SQLite path](#sqlite-path) | `~/.influxdbv2/influxd.sqlite` | +| [Configs path](#configs-path) | `~/.influxdbv2/configs` | + +#### macOS file system overview +{{% filesystem-diagram %}} +- ~/.influxdbv2/ + - engine/ + - data/ + - _TSM directories and files_ + - wal/ + - _WAL directories and files_ + - configs + - influxd.bolt + - influxd.sqlite +{{% /filesystem-diagram %}} +{{% /tab-content %}} + + + +{{% tab-content %}} +When installing InfluxDB on Linux, you can download and install the `influxd` binary, +or you can use a package manager. +Which installation method you use determines the file system layout. + +- [Installed as a standalone binary](#installed-as-a-standalone-binary) +- [Installed as a package](#installed-as-a-package) + +### Installed as a standalone binary + +#### Linux default paths (standalone binary) +| Path | Default | +|:---- |:------- | +| [Engine path](#engine-path) | `~/.influxdbv2/engine/` | +| [Bolt path](#bolt-path) | `~/.influxdbv2/influxd.bolt` | +| [SQLite path](#sqlite-path) | `~/.influxdbv2/influxd.sqlite` | +| [Configs path](#configs-path) | `~/.influxdbv2/configs` | + +#### Linux file system overview (standalone binary) +{{% filesystem-diagram %}} +- ~/.influxdbv2/ + - engine/ + - data/ + - _TSM directories and files_ + - wal/ + - _WAL directories and files_ + - configs + - influxd.bolt + - influxd.sqlite +{{% /filesystem-diagram %}} + +### Installed as a package +InfluxDB {{< current-version >}} supports **.deb-** and **.rpm-based** Linux package managers. +The file system layout is the same with each. + +#### Linux default paths (package) +| Path | Default | +|:----------------------------------------------------------|:-----------------------------------| +| [Engine path](#engine-path) | `/var/lib/influxdb/engine/` | +| [Bolt path](#bolt-path) | `/var/lib/influxdb/influxd.bolt` | +| [SQLite path](#sqlite-path) | `/var/lib/influxdb/influxd.sqlite` | +| [Configs path](#configs-path) | `/var/lib/influxdb/configs` | +| [Default config file path](#influxdb-configuration-files) | `/etc/influxdb/config.toml` | + +#### Linux file system overview (package) +{{% filesystem-diagram %}} +- /var/lib/influxdb/ + - engine/ + - data/ + - _TSM directories and files_ + - wal/ + - _WAL directories and files_ + - configs + - influxd.bolt + - influxd.sqlite +- /etc/influxdb/ + - config.toml _(influxd configuration file)_ +{{% /filesystem-diagram %}} +{{% /tab-content %}} + + + +{{% tab-content %}} + +#### Windows default paths +| Path | Default | +|:---- |:------- | +| [Engine path](#engine-path) | `%USERPROFILE%\.influxdbv2\engine\` | +| [Bolt path](#bolt-path) | `%USERPROFILE%\.influxdbv2\influxd.bolt` | +| [SQLite path](#sqlite-path) | `%USERPROFILE%\.influxdbv2\influxd.sqlite` | +| [Configs path](#configs-path) | `%USERPROFILE%\.influxdbv2\configs` | + +#### Windows file system overview +{{% filesystem-diagram %}} +- %USERPROFILE%\\.influxdbv2\ + - engine\ + - data\ + - _TSM directories and files_ + - wal\ + - _WAL directories and files_ + - configs + - influxd.bolt + - influxd.sqlite +{{% /filesystem-diagram %}} +{{% /tab-content %}} + + + +{{% tab-content %}} +InfluxDB Docker images are available from both [Dockerhub](https://hub.docker.com/_/influxdb) +and [Quay.io](https://quay.io/repository/influxdb/influxdb?tab=tags). +Each have a unique InfluxDB file system layout. + +- [Dockerhub](#dockerhub) +- [Quay.io](#quayio) + +### Dockerhub + +{{% note %}} +The InfluxDB Dockerhub image uses `/var/lib/influxdb2` instead of `/var/lib/influxdb` +so you can easily mount separate volumes for InfluxDB 1.x and 2.x data during the +[upgrade process](/influxdb/v2.1/upgrade/v1-to-v2/docker/). +{{% /note %}} + +#### Dockerhub default paths +| Path | Default | +|:---- |:------- | +| [Engine path](#engine-path) | `/var/lib/influxdb2/engine/` | +| [Bolt path](#bolt-path) | `/var/lib/influxdb2/influxd.bolt` | +| [SQLite path](#sqlite-path) | `/var/lib/influxdb2/influxd.sqlite` | +| [Configs path](#configs-path) | `/etc/influxdb2/configs` | + +#### Dockerhub file system overview +{{% filesystem-diagram %}} +- /var/lib/influxdb2/ + - engine/ + - data/ + - _TSM directories and files_ + - wal/ + - _WAL directories and files_ + - influxd.bolt + - influxd.sqlite +- /etc/influxdb2/ + - configs +{{% /filesystem-diagram %}} + +### Quay.io + +#### Quay default paths +| Path | Default | +|:---- |:------- | +| [Engine path](#engine-path) | `/root/.influxdbv2/engine/` | +| [Bolt path](#bolt-path) | `/root/.influxdbv2/influxd.bolt` | +| [SQLite path](#sqlite-path) | `/root/.influxdbv2/influxd.sqlite` | +| [Configs path](#configs-path) | `/root/.influxdbv2/configs` | + +#### Quay file system overview +{{% filesystem-diagram %}} +- /root/.influxdbv2/ + - engine/ + - data/ + - _TSM directories and files_ + - wal/ + - _WAL directories and files_ + - configs + - influxd.bolt + - influxd.sqlite +{{% /filesystem-diagram %}} +{{% /tab-content %}} + + + +{{% tab-content %}} +#### Kubernetes default paths +| Path | Default | +|:------------------------------|:------------------------------------| +| [Engine path](#engine-path) | `/var/lib/influxdb2/engine/` | +| [Bolt path](#bolt-path) | `/var/lib/influxdb2/influxd.bolt` | +| [SQLite path](#sqlite-path) | `/var/lib/influxdb2/influxd.sqlite` | +| [Configs path](#configs-path) | `/etc/influxdb2/configs` | + +#### Kubernetes file system overview +{{% filesystem-diagram %}} +- /var/lib/influxdb2/ + - engine/ + - data/ + - _TSM directories and files_ + - wal/ + - _WAL directories and files_ + - influxd.bolt + - influxd.sqlite +- /etc/influxdb2/ + - configs +{{% /filesystem-diagram %}} +{{% /tab-content %}} + +{{< /tabs-wrapper >}} diff --git a/content/influxdb/v2.1/reference/internals/shards.md b/content/influxdb/v2.1/reference/internals/shards.md new file mode 100644 index 0000000000..d0b38dee53 --- /dev/null +++ b/content/influxdb/v2.1/reference/internals/shards.md @@ -0,0 +1,145 @@ +--- +title: InfluxDB shards and shard groups +description: > + Learn the relationships between buckets, shards, and shard groups. + InfluxDB organizes time series data into **shards** when storing data to disk. + Shards are grouped into **shard groups**. +menu: + influxdb_2_1_ref: + name: Shards & shard groups + parent: InfluxDB internals +weight: 102 +influxdb/v2.1/tags: [storage, internals] +related: + - /influxdb/v2.1/reference/internals/storage-engine/ + - /influxdb/v2.1/organizations/buckets/ + - /influxdb/v2.1/reference/cli/influx/bucket/ +--- + +InfluxDB organizes time series data into **shards** when storing data to disk. +Shards are grouped into **shard groups**. +Learn the relationships between buckets, shards, and shard groups. + +- [Shards](#shards) +- [Shard groups](#shard-groups) + - [Shard group duration](#shard-group-duration) + - [Shard group diagram](#shard-group-diagram) +- [Shard life-cycle](#shard-life-cycle) + - [Shard precreation](#shard-precreation) + - [Shard writes](#shard-writes) + - [Shard compaction](#shard-compaction) +- [Shard deletion](#shard-deletion) + +## Shards +A shard contains encoded and compressed time series data for a given time range +defined by the [shard group duration](#shard-group-duration). +All points in a [series](#series) within the specified shard group duration are stored in the same shard. +A single shard contains multiple series, one or more [TSM files](#tsm-time-structured-merge-tree) on disk, +and belongs to a [shard group](#shard-groups). + +## Shard groups +A shard group belongs to an InfluxDB [bucket](/influxdb/v2.1/reference/glossary/#bucket) and contains time series data for a specific time range defined by +the [shard group duration](#shard-group-duration). + +{{% note %}} +In **InfluxDB OSS**, a shard group typically contains only a single shard. +In an **InfluxDB Enterprise 1.x cluster**, shard groups contain multiple shards +distributed across multiple data nodes. +{{% /note %}} + +### Shard group duration +The **shard group duration** specifies the time range for each shard group and determines how often to create a new shard group. +By default, InfluxDB sets the shard group duration according to +the [retention period](/influxdb/v2.1/reference/glossary/#retention-period) +of the bucket: + +| Bucket retention period | Default shard group duration | +|:----------------------- | ----------------------------:| +| less than 2 days | 1h | +| between 2 days and 6 months | 1d | +| greater than 6 months | 7d | + +##### Shard group duration configuration options +To configure a custom bucket shard group duration, use the `--shard-group-duration` +flag with the [`influx bucket create`](/influxdb/v2.1/reference/cli/influx/bucket/create/#create-a-custom-shard-group-duration) +and [`influx bucket update`](/influxdb/v2.1/reference/cli/influx/bucket/update//#update-the-shard-group-duration-of-a-bucket) commands. + +{{% note %}} +Shard group durations must be shorter than the bucket's retention period. +{{% /note %}} + +To view your bucket's shard group duration, use the +[`influx bucket list` command](/influxdb/v2.1/reference/cli/influx/bucket/list/). + +### Shard group diagram +The following diagram represents a **bucket** with a **4d retention period** +and a **1d shard group duration**: + +--- + +{{< html-diagram/shards >}} + +--- + +## Shard life-cycle + +### Shard precreation +The InfluxDB **shard precreation service** pre-creates shards with future start +and end times for each shard group based on the shard group duration. + +The precreator service does not pre-create shards for past time ranges. +When backfilling historical data, InfluxDB creates shards for past time ranges as needed, +resulting in temporarily lower write throughput. + +##### Shard precreation-related configuration settings +- [`storage-shard-precreator-advance-period`](/influxdb/v2.1/reference/config-options/#storage-shard-precreator-advance-period) +- [`storage-shard-precreator-check-interval`](/influxdb/v2.1/reference/config-options/#storage-shard-precreator-check-interval) + +### Shard writes +InfluxDB writes time series data to un-compacted or "hot" shards. +When a shard is no longer actively written to, InfluxDB [compacts](#shard-compaction) shard data, resulting in a "cold" shard. + +Typically, InfluxDB writes data to the most recent shard group, but when backfilling +historical data, InfluxDB writes to older shards that must first be un-compacted. +When the backfill is complete, InfluxDB re-compacts the older shards. + +### Shard compaction +InfluxDB compacts shards at regular intervals to compress time series data and optimize disk usage. +InfluxDB uses the following four compaction levels: + +- **Level 1 (L1):** InfluxDB flushes all newly written data held in an in-memory cache to disk. +- **Level 2 (L2):** InfluxDB compacts up to eight L1-compacted files into one or more L2 files by + combining multiple blocks containing the same series into fewer blocks in one or more new files. +- **Level 3 (L3):** InfluxDB iterates over L2-compacted file blocks (over a certain size) + and combines multiple blocks containing the same series into one block in a new file. +- **Level 4 (L4):** **Full compaction**—InfluxDB iterates over L3-compacted file blocks + and combines multiple blocks containing the same series into one block in a new file. + +##### Shard compaction-related configuration settings +- [`storage-compact-full-write-cold-duration`](/influxdb/v2.1/reference/config-options/#storage-compact-full-write-cold-duration) +- [`storage-compact-throughput-burst`](/influxdb/v2.1/reference/config-options/#storage-compact-throughput-burst) +- [`storage-max-concurrent-compactions`](/influxdb/v2.1/reference/config-options/#storage-max-concurrent-compactions) +- [`storage-max-index-log-file-size`](/influxdb/v2.1/reference/config-options/#storage-max-index-log-file-size) +- [`storage-series-file-max-concurrent-snapshot-compactions`](/influxdb/v2.1/reference/config-options/#storage-series-file-max-concurrent-snapshot-compactions) +- [`storage-series-file-max-concurrent-snapshot-compactions`](/influxdb/v2.1/reference/config-options/#storage-series-file-max-concurrent-snapshot-compactions) + +## Shard deletion +The InfluxDB **retention enforcement service** routinely checks for shard groups +older than their bucket's retention period. +Once the start time of a shard group is beyond the bucket's retention period, +InfluxDB deletes the shard group and associated shards and TSM files. + +In buckets with an infinite retention period, shards remain on disk indefinitely. + +{{% note %}} +#### InfluxDB only deletes cold shards +InfluxDB only deletes **cold** shards. +If backfilling data beyond a bucket's retention period, the backfilled data will +remain on disk until the following occurs: + +1. The shard returns to a cold state. +2. The retention enforcement service deletes the shard group. +{{% /note %}} + +##### Retention enforcement-related configuration settings +- [`storage-retention-check-interval`](/influxdb/v2.1/reference/config-options/#storage-retention-check-interval) diff --git a/content/influxdb/v2.1/reference/internals/storage-engine.md b/content/influxdb/v2.1/reference/internals/storage-engine.md new file mode 100644 index 0000000000..c4b0e92121 --- /dev/null +++ b/content/influxdb/v2.1/reference/internals/storage-engine.md @@ -0,0 +1,104 @@ +--- +title: InfluxDB storage engine +description: > + An overview of the InfluxDB storage engine architecture. +weight: 101 +menu: + influxdb_2_1_ref: + name: Storage engine + parent: InfluxDB internals +influxdb/v2.1/tags: [storage, internals] +products: [oss] +--- + +The InfluxDB storage engine ensures that: + +- Data is safely written to disk +- Queried data is returned complete and correct +- Data is accurate (first) and performant (second) + +This document outlines the internal workings of the storage engine. +This information is presented both as a reference and to aid those looking to maximize performance. + +The storage engine includes the following components: + +* [Write Ahead Log (WAL)](#write-ahead-log-wal) +* [Cache](#cache) +* [Time-Structed Merge Tree (TSM)](#time-structured-merge-tree-tsm) +* [Time Series Index (TSI)](#time-series-index-tsi) + +## Writing data from API to disk + +The storage engine handles data from the point an API write request is received through writing data to the physical disk. +Data is written to InfluxDB using [line protocol](/influxdb/v2.1/reference/syntax/line-protocol/) sent via HTTP POST request to the `/write` endpoint. +Batches of [points](/influxdb/v2.1/reference/glossary/#point) are sent to InfluxDB, compressed, and written to a WAL for immediate durability. +Points are also written to an in-memory cache and become immediately queryable. +The in-memory cache is periodically written to disk in the form of [TSM](#time-structured-merge-tree-tsm) files. +As TSM files accumulate, the storage engine combines and compacts accumulated them into higher level TSM files. + +{{% note %}} +While points can be sent individually, for efficiency, most applications send points in batches. +Points in a POST body can be from an arbitrary number of series, measurements, and tag sets. +Points in a batch do not have to be from the same measurement or tagset. +{{% /note %}} + +## Write Ahead Log (WAL) + +The **Write Ahead Log** (WAL) retains InfluxDB data when the storage engine restarts. +The WAL ensures data is durable in case of an unexpected failure. + +When the storage engine receives a write request, the following steps occur: + +1. The write request is appended to the end of the WAL file. +2. Data is written to disk using `fsync()`. +3. The in-memory cache is updated. +4. When data is successfully written to disk, a response confirms the write request was successful. + +`fsync()` takes the file and pushes pending writes all the way to the disk. +As a system call, `fsync()` has a kernel context switch that's computationally expensive, but guarantees that data is safe on disk. + +When the storage engine restarts, the WAL file is read back into the in-memory database. +InfluxDB then answers requests to the `/read` endpoint. + +## Cache + +The **cache** is an in-memory copy of data points currently stored in the WAL. +The cache: + +- Organizes points by key (measurement, tag set, and unique field) + Each field is stored in its own time-ordered range. +- Stores uncompressed data. +- Gets updates from the WAL each time the storage engine restarts. + The cache is queried at runtime and merged with the data stored in TSM files. + +Queries to the storage engine merge data from the cache with data from the TSM files. +Queries execute on a copy of the data that is made from the cache at query processing time. +This way writes that come in while a query is running do not affect the result. +Deletes sent to the cache clear the specified key or time range for a specified key. + +## Time-Structured Merge Tree (TSM) + +To efficiently compact and store data, +the storage engine groups field values by series key, and then orders those field values by time. +(A [series key](/influxdb/v2.1/reference/glossary/#series-key) is defined by measurement, tag key and value, and field key.) + +The storage engine uses a **Time-Structured Merge Tree** (TSM) data format. +TSM files store compressed series data in a columnar format. +To improve efficiency, the storage engine only stores differences (or *deltas*) between values in a series. +Column-oriented storage lets the engine read by series key and omit extraneous data. + +After fields are stored safely in TSM files, the WAL is truncated and the cache is cleared. +The TSM compaction code is quite complex. +However, the high-level goal is quite simple: +organize values for a series together into long runs to best optimize compression and scanning queries. + +## Time Series Index (TSI) + +As data cardinality (the number of series) grows, queries read more series keys and become slower. +The **Time Series Index** ensures queries remain fast as data cardinality grows. +The TSI stores series keys grouped by measurement, tag, and field. +This allows the database to answer two questions well: + +- What measurements, tags, fields exist? + (This happens in meta queries.) +- Given a measurement, tags, and fields, what series keys exist? diff --git a/content/influxdb/v2.1/reference/internals/system-buckets.md b/content/influxdb/v2.1/reference/internals/system-buckets.md new file mode 100644 index 0000000000..2d464ccbfb --- /dev/null +++ b/content/influxdb/v2.1/reference/internals/system-buckets.md @@ -0,0 +1,93 @@ +--- +title: InfluxDB system buckets +description: > + InfluxDB system buckets contain time series data used by and generated from the + InfluxDB monitoring and alerting system and the task engine. +menu: + influxdb_2_1_ref: + name: System buckets + parent: InfluxDB internals +weight: 103 +influxdb/v2.1/tags: [buckets] +related: + - /influxdb/v2.1/monitor-alert/ + - /influxdb/v2.1/process-data/ + - /{{< latest "flux" >}}/stdlib/influxdata/influxdb/monitor/check/ + - /{{< latest "flux" >}}/stdlib/influxdata/influxdb/monitor/deadman/ + - /{{< latest "flux" >}}/stdlib/influxdata/influxdb/monitor/from/ + - /{{< latest "flux" >}}/stdlib/influxdata/influxdb/monitor/logs/ + - /{{< latest "flux" >}}/stdlib/influxdata/influxdb/monitor/notify/ +--- + +InfluxDB system buckets contain time series data used by and generated from the +InfluxDB monitoring and alerting system and the task engine. + +Each InfluxDB organization includes the following system buckets: + +- [\_monitoring](#_monitoring-system-bucket) +- [\_tasks](#_tasks-system-bucket) + +{{% note %}} +The system bucket schemas below reference **InfluxDB data elements**. +For more information, see [InfluxDB key concepts](/influxdb/v2.1/reference/key-concepts/data-elements/). +{{% /note %}} + +## \_monitoring system bucket +The `_monitoring` system bucket stores InfluxDB data used to +[monitor data and send alerts](/influxdb/v2.1/monitor-alert/). + +**Data retention:** 7 days + +### \_monitoring bucket schema + +- **statuses** _(measurement)_ + - **tags:** + - **\_check\_id:** check ID + - **\_check\_name:** check name + - **\_level:** level evaluated by the check (ok, info, warn, or crit) + - **\_source\_measurement:** original measurement queried by the check + - **\_type:** check type (threshold or deadman) + - _other tags inherited from queried data or added in the check configuration_ + - **fields:** + - **\_message:** message generated by the check + - **\_source_timestamp:** original timestamp of the queried data + - _other fields inherited from queried data_ +- **notifications** _(measurement)_ + - **tags:** + - **\_check\_id:** check ID that triggered the notification + - **\_check\_name:** check name that triggered the notification + - **\_level:** check-evaluated level that triggered the notification (ok, info, warn, or crit) + - **\_notification_endpoint_id:** notification endpoint ID + - **\_notification_endpoint_name:** notification endpoint name + - **\_notification_rule_id:** notification rule ID + - **\_notification_rule_name:** notification rule name + - **\_sent:** sent status (true or false) + - **\_source\_measurement:** original measurement queried by the check + - **\_type:** check type (threshold or deadman) + - _other tags inherited from queried data or added in the check configuration_ + - **fields:** + - **\_message:** message generated by the check + - **\_source_timestamp:** original timestamp of the queried data + - **\_status_timestamp:** timestamp when the status (`_level`) was evaluated + - _other fields inherited from queried data_ + +## \_tasks system bucket +The `_tasks` system bucket stores data related to [InfluxDB task](/influxdb/v2.1/process-data/) executions. + +**Data retention:** 3 days + +### \_tasks bucket schema + +_A **task run** refers to a single task execution._ + +- **runs** _(measurement)_ + - **tags:** + - **status:** task run status (success or failed) + - **taskID:** task ID + - **fields:** + - **finishedAt:** timestamp when the task run finished + - **logs:** log output from the task run + - **requestedAt:** timestamp when the task run was requested + - **runID** task run ID + - **scheduledFor:** timestamp the task run was scheduled for + - **startedAt:** timestamp when the task run started diff --git a/content/influxdb/v2.1/reference/key-concepts/_index.md b/content/influxdb/v2.1/reference/key-concepts/_index.md new file mode 100644 index 0000000000..91e7ebd99a --- /dev/null +++ b/content/influxdb/v2.1/reference/key-concepts/_index.md @@ -0,0 +1,14 @@ +--- +title: InfluxDB key concepts +description: > + Concepts related to InfluxDB. +weight: 2 +menu: + influxdb_2_1_ref: + name: Key concepts +influxdb/v2.1/tags: [key concepts] +--- + +Before working with InfluxDB {{< current-version >}}, it's helpful to learn a few key concepts. Browse the topics below to learn more. + +{{< children >}} diff --git a/content/influxdb/v2.1/reference/key-concepts/data-elements.md b/content/influxdb/v2.1/reference/key-concepts/data-elements.md new file mode 100644 index 0000000000..257bcc2ce8 --- /dev/null +++ b/content/influxdb/v2.1/reference/key-concepts/data-elements.md @@ -0,0 +1,201 @@ +--- +title: InfluxDB data elements +description: > + InfluxDB structures data using elements such as timestamps, field keys, field values, tags, etc. +weight: 102 +menu: + influxdb_2_1_ref: + parent: Key concepts + name: Data elements +influxdb/v2.1/tags: [key concepts, schema] +--- + +InfluxDB {{< current-version >}} includes the following data elements: + +- [timestamp](#timestamp) +- [field key](#field-key) +- [field value](#field-value) +- [field set](#field-set) +- [tag key](#tag-key) +- [tag value](#tag-value) +- [tag set](#tag-set) +- [measurement](#measurement) +- [series](#series) +- [point](#point) +- [bucket](#bucket) +- [bucket schema](#bucket-schema) +- [organization](#organization) + +The sample data below is used to illustrate data elements concepts. +_Hover over highlighted terms to get acquainted with InfluxDB terminology and layout._ + + +**bucket:** `my_bucket` + +| _time | _measurement | {{< tooltip "Tag key" "location" >}} | {{< tooltip "Tag key" "scientist" >}} | _field | _value | +|:------------------- |:------------ |:------- |:------ |:-- |:------ | +| 2019-08-18T00:00:00Z | census | klamath | anderson | bees | 23 | +| 2019-08-18T00:00:00Z | census | portland | mullen | ants | 30 | +| 2019-08-18T00:06:00Z | census | klamath | anderson | bees | 28 | +| {{< tooltip "Timestamp" "2019-08-18T00:06:00Z" >}} | {{< tooltip "measurement" "census" >}} | {{< tooltip "Tag value" "portland" >}} | {{< tooltip "Tag value" "mullen">}} | {{< tooltip "Field key" "ants" >}} | {{< tooltip "Field value" "32" >}} | + +## Timestamp + +All data stored in InfluxDB has a `_time` column that stores timestamps. On disk, timestamps are stored in epoch nanosecond format. InfluxDB formats timestamps show the date and time in [RFC3339](/influxdb/v2.1/reference/glossary/#rfc3339-timestamp) UTC associated with data. Timestamp precision is important when you write data. + +## Measurement + +The `_measurement` column shows the name of the measurement `census`. Measurement names are strings. A measurement acts as a container for tags, fields, and timestamps. Use a measurement name that describes your data. The name `census` tells us that the field values record the number of `bees` and `ants`. + +## Fields + +A field includes a field key stored in the `_field` column and a field value stored in the `_value` column. + +### Field key + +A field key is a string that represents the name of the field. In the sample data above, `bees` and `ants` are field keys. + +### Field value + +A field value represents the value of an associated field. Field values can be strings, floats, integers, or booleans. The field values in the sample data show the number of `bees` at specified times: `23`, and `28` and the number of `ants` at a specified time: `30` and `32`. + +### Field set + +A field set is a collection of field key-value pairs associated with a timestamp. The sample data includes the following field sets: + +```bash + +census bees=23i,ants=30i 1566086400000000000 +census bees=28i,ants=32i 1566086760000000000 + ----------------- + Field set + +``` + +{{% note %}} +**Fields aren't indexed:** Fields are required in InfluxDB data and are not indexed. Queries that filter field values must scan all field values to match query conditions. As a result, queries on tags > are more performant than queries on fields. **Store commonly queried metadata in tags.** +{{% /note %}} + +## Tags + +The columns in the sample data, `location` and `scientist`, are tags. +Tags include tag keys and tag values that are stored as strings and metadata. + +### Tag key + +The tag keys in the sample data are `location` and `scientist`. +_For information about tag key requirements, see [Line protocol – Tag set](/influxdb/v2.1/reference/syntax/line-protocol/#tag-set)._ + +### Tag value + +The tag key `location` has two tag values: `klamath` and `portland`. +The tag key `scientist` also has two tag values: `anderson` and `mullen`. +_For information about tag value requirements, see [Line protocol – Tag set](/influxdb/v2.1/reference/syntax/line-protocol/#tag-set)._ + +### Tag set + +The collection of tag key-value pairs make up a tag set. The sample data includes the following four tag sets: + +```bash +location = klamath, scientist = anderson +location = portland, scientist = anderson +location = klamath, scientist = mullen +location = portland, scientist = mullen +``` + +{{% note %}} +**Tags are indexed:** Tags are optional. You don't need tags in your data structure, but it's typically a good idea to include tags. +Because tags are indexed, queries on tags are faster than queries on fields. This makes tags ideal for storing commonly-queried metadata. +{{% /note %}} + +{{% note %}} +Tags containing highly variable information like UUIDs, hashes, and random strings will lead to a large number of unique series in the database, known as **high series cardinality**. High series cardinality is a primary driver of high memory usage for many database workloads. See [series cardinality](/influxdb/v2.1/reference/glossary/#series-cardinality) for more information. +{{% /note %}} + + +#### Why your schema matters + +If most of your queries focus on values in the fields, for example, a query to find when 23 bees were counted: + +```js +from(bucket: "bucket-name") + |> range(start: 2019-08-17T00:00:00Z, stop: 2019-08-19T00:00:00Z) + |> filter(fn: (r) => r._field == "bees" and r._value == 23) +``` + +InfluxDB scans every field value in the dataset for `bees` before the query returns a response. If our sample `census` data grew to millions of rows, to optimize your query, you could rearrange your [schema](/influxdb/v2.1/reference/glossary/#schema) so the fields (`bees` and `ants`) becomes tags and the tags (`location` and `scientist`) become fields: + +| _time | _measurement | {{< tooltip "Tag key" "bees" >}} | _field | _value | +|:------------------- |:------------ |:------- |:-- |:------ | +| 2019-08-18T00:00:00Z | census | 23 | location | klamath | +| 2019-08-18T00:00:00Z | census | 23 | scientist | anderson | +| 2019-08-18T00:06:00Z | census | {{< tooltip "Tag value" "28" >}} | {{< tooltip "Field key" "location" >}} | {{< tooltip "Field value" "klamath" >}} | +| 2019-08-18T00:06:00Z | census | 28 | scientist | anderson | + +| _time | _measurement | {{< tooltip "Tag key" "ants" >}} | _field | _value | +|:------------------- |:------------ |:------- |:-- |:------ | +| 2019-08-18T00:00:00Z | census | 30 | location | portland | +| 2019-08-18T00:00:00Z | census | 30 | scientist | mullen | +| 2019-08-18T00:06:00Z | census | {{< tooltip "Tag value" "32" >}} | {{< tooltip "Field key" "location" >}} | {{< tooltip "Field value" "portland" >}} | +| 2019-08-18T00:06:00Z | census | 32 | scientist | mullen | + +Now that `bees` and `ants` are tags, InfluxDB doesn't have to scan all `_field` and `_value` columns. This makes your queries faster. + +## Bucket schema + +In InfluxDB Cloud, a bucket with the `explicit` schema-type requires an explicit +schema for each measurement. +Measurements contain tags, fields, and timestamps. +An explicit schema constrains the shape of data that can be written to that measurement. + +The following schema constrains `census` data: + +name | type | data_type +|:------- |:---------------|:-------------------- +time | timestamp | +location | tag | string +scientist | tag | string +ants | field | integer +bees | field | integer + +## Series + +Now that you're familiar with measurements, field sets, and tag sets, it's time to discuss series keys and series. A **series key** is a collection of points that share a measurement, tag set, and field key. For example, the [sample data](#sample-data) includes two unique series keys: + +| _measurement | tag set | _field | +|:------------- |:------------------------------- |:------ | +| census | {{< tooltip "Tag set" "location=klamath,scientist=anderson" >}} | {{< tooltip "Field key" "bees" >}} | +| census | location=portland,scientist=mullen | ants | + +A **series** includes timestamps and field values for a given series key. From the sample data, here's a **series key** and the corresponding **series**: + +```bash +# series key +census,location=klamath,scientist=anderson bees + +# series +2019-08-18T00:00:00Z 23 +2019-08-18T00:06:00Z 28 +``` + +Understanding the concept of a series is essential when designing your [schema](/influxdb/v2.1/reference/glossary/#schema) and working with your data in InfluxDB. + +## Point + +A **point** includes the series key, a field value, and a timestamp. For example, a single point from the [sample data](#sample-data) looks like this: + +`2019-08-18T00:00:00Z census ants 30 portland mullen` + +## Bucket + +All InfluxDB data is stored in a bucket. A **bucket** combines the concept of a database and a retention period (the duration of time that each data point persists). A bucket belongs to an organization. For more information about buckets, see [Manage buckets](/influxdb/v2.1/organizations/buckets/). + +## Organization + +An InfluxDB **organization** is a workspace for a group of [users](/influxdb/v2.1/users/). All [dashboards](/influxdb/v2.1/visualize-data/dashboards/), [tasks](/influxdb/v2.1/process-data/), buckets, and users belong to an organization. For more information about organizations, see [Manage organizations](/influxdb/v2.1/organizations/). + +If you're just starting out, we recommend taking a look at the following guides: + +- [Get started](/influxdb/v2.1/get-started) +- [Write data](/influxdb/v2.1/write-data) +- [Query data](/influxdb/v2.1/query-data) diff --git a/content/influxdb/v2.1/reference/key-concepts/data-schema.md b/content/influxdb/v2.1/reference/key-concepts/data-schema.md new file mode 100644 index 0000000000..a6f91f6f60 --- /dev/null +++ b/content/influxdb/v2.1/reference/key-concepts/data-schema.md @@ -0,0 +1,63 @@ +--- +title: InfluxDB data schema +description: > + InfluxDB uses a tabular data schema for displaying raw data in Data Explorer and for returning query results in annotated CSV syntax. +aliases: + - /influxdb/v2.1/reference/key-concepts/table-structure +weight: 103 +menu: + influxdb_2_1_ref: + parent: Key concepts + name: Data schema +influxdb/v2.1/tags: [key concepts] +--- + +InfluxDB [data elements](/influxdb/v2.1/reference/key-concepts/data-elements/) are stored in **time-structured merge tree (TSM)** and **time series index (TSI)** files to efficiently compact stored data. + +InfluxDB also provides a **tabular data schema** that includes the following: + +- [Annotation rows](#annotation-rows) +- [Header row](#header-row) +- [Data rows](#data-rows) +- [Other columns](#other-columns) +- [Group keys](#group-keys) + +The **tabular data schema is used for the following**: + +- To [view raw data](/influxdb/v2.1/query-data/execute-queries/data-explorer/#view-raw-data) when [exploring metrics with InfluxDB](/influxdb/v2.1/visualize-data/explore-metrics) +- To return query results in [annotated CSV syntax](/influxdb/v2.1/reference/syntax/annotated-csv/) + +## Annotation rows + +Annotation rows describe column properties, for example: + +- `#group` +- `#datatype` +- `#default` + +## Header row + +The header row defines column labels that describe data in each column, for example: + +- `table` +- `_time` +- `_value` +- `_field` +- `_measurement` +- tag key names (without underscore prefix): `tag-1`, `tag-2` + +## Data rows + +Each data row contains the data specified in the header row for one [point](/influxdb/v2.1/reference/glossary/#point). + +## Other columns + +In addition to the columns in each data row (specified in the header row), the following columns are optional: + +- `annotation` +- `result` +- `table` + +## Group keys + +Determine the contents of output tables in Flux by grouping records that share common values in specified columns. Learn more about [grouping your data with Flux](/influxdb/v2.1/query-data/flux/group-data/). diff --git a/content/influxdb/v2.1/reference/key-concepts/design-principles.md b/content/influxdb/v2.1/reference/key-concepts/design-principles.md new file mode 100644 index 0000000000..8c658d44cd --- /dev/null +++ b/content/influxdb/v2.1/reference/key-concepts/design-principles.md @@ -0,0 +1,44 @@ +--- +title: InfluxDB design principles +description: > + Principles and tradeoffs related to InfluxDB design. +weight: 104 +menu: + influxdb_2_1_ref: + parent: Key concepts + name: Design principles +influxdb/v2.1/tags: [key concepts, design principles] +--- + +InfluxDB implements optimal design principles for time series data. Some of these design principles may have associated tradeoffs in performance. + +- [Time-ordered data](#time-ordered-data) +- [Strict update and delete permissions](#strict-update-and-delete-permissions) +- [Handle read and write queries first](#handle-read-and-write-queries-first) +- [Schemaless design](#schemaless-design) +- [Datasets over individual points](#datasets-over-individual-points) +- [Duplicate data](#duplicate-data) + +## Time-ordered data + +To improve performance, data is written in time-ascending order. + +## Strict update and delete permissions + +To increase query and write performance, InfluxDB tightly restricts **update** and **delete** permissions. Time series data is predominantly new data that is never updated. Deletes generally only affect data that isn't being written to, and contentious updates never occur. + +## Handle read and write queries first + +InfluxDB prioritizes read and write requests over strong consistency. InfluxDB returns results when a query is executed. Any transactions that affect the queried data are processed subsequently to ensure that data is eventually consistent. Therefore, if the ingest rate is high (multiple writes per ms), query results may not include the most recent data. + +## Schemaless design + +InfluxDB uses a schemaless design to better manage discontinuous data. Time series data are often ephemeral, meaning the data appears for a few hours and then goes away. For example, a new host that gets started and reports for a while and then gets shut down. + +## Datasets over individual points + +Because the data set is more important than an individual point, InfluxDB implements powerful tools to aggregate data and handle large data sets. Points are differentiated by timestamp and series, so don’t have IDs in the traditional sense. + +## Duplicate data + +To simplify conflict resolution and increase write performance, InfluxDB assumes data sent multiple times is duplicate data. Identical points aren't stored twice. If a new field value is submitted for a point, InfluxDB updates the point with the most recent field value. In rare circumstances, data may be overwritten. Learn more about [duplicate points](/influxdb/v2.1/write-data/best-practices/duplicate-points/). diff --git a/content/influxdb/v2.1/reference/prometheus-metrics.md b/content/influxdb/v2.1/reference/prometheus-metrics.md new file mode 100644 index 0000000000..08cd92c8ba --- /dev/null +++ b/content/influxdb/v2.1/reference/prometheus-metrics.md @@ -0,0 +1,286 @@ +--- +title: Prometheus metric parsing formats +description: > + When scraping [Prometheus-formatted metrics](https://prometheus.io/docs/concepts/data_model/) + and writing them to InfluxDB, metrics are parsed and stored in InfluxDB in different formats. +menu: + influxdb_2_1_ref: + name: Prometheus metrics +weight: 8 +influxdb/v2.1/tags: [prometheus] +related: + - https://prometheus.io/docs/concepts/data_model/, Prometheus data model + - /influxdb/v2.1/write-data/developer-tools/scrape-prometheus-metrics/ + - /{{< latest "flux" >}}/prometheus/, Work with Prometheus in Flux + - /{{< latest "telegraf" >}}/plugins/#prometheus, Telegraf Prometheus input plugin + - /influxdb/v2.1/write-data/no-code/scrape-data/ + - /{{< latest "flux" >}}/stdlib/experimental/prometheus/scrape/ +--- + +[Prometheus-formatted metrics](https://prometheus.io/docs/concepts/data_model/) +are parsed and written to InfluxDB in one of two formats, depending on the scraping tool used: + +- [Metric version 1](#metric-version-1) +- [Metric version 2](#metric-version-2) + +#### Scraping tools and parsing format +{{% oss-only %}} + +| Scraping tool | InfluxDB Metric version | +| :----------------------------------------------------------------------------------------- | ----------------------------------------------------: | +| [Telegraf Prometheus plugin](/{{< latest "telegraf" >}}/plugins/#prometheus) | _Determined by `metric_version` configuration option_ | +| [InfluxDB scraper](/influxdb/v2.1/write-data/no-code/scrape-data/) | 1 | +| Flux [`prometheus.scrape()`]({{< latest "flux" >}}/stdlib/experimental/prometheus/scrape/) | 2 | + +{{% /oss-only %}} +{{% cloud-only %}} + +| Scraping tool | InfluxDB Metric version | +| :----------------------------------------------------------------------------------------- | ----------------------------------------------------: | +| [Telegraf Prometheus plugin](/{{< latest "telegraf" >}}/plugins/#prometheus) | _Determined by `metric_version` configuration option_ | +| Flux [`prometheus.scrape()`]({{< latest "flux" >}}/stdlib/experimental/prometheus/scrape/) | 2 | + +{{% /cloud-only %}} + +## Metric version 1 + +- **_time**: timestamp +- **_measurement**: [Prometheus metric name](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels) + _(`_bucket`, `_sum`, and `_count` are trimmed from histogram and summary metric names)_ +- **\_field**: _depends on the [Prometheus metric type](https://prometheus.io/docs/concepts/metric_types/)_ + - Counter: `counter` + - Gauge: `gauge` + - Histogram: _histogram bucket upper limits_, `count`, `sum` + - Summary: _summary quantiles_, `count`, `sum` +- **_value**: [Prometheus metric value](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels) +- **tags**: A tag for each [Prometheus label](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels) + _(except for histogram bucket upper limits (`le`) or summary quantiles (`quantile`))_. + The label name is the tag key and the label value is the tag value. + +### Example Prometheus query results +The following are example Prometheus metrics scraped from the **InfluxDB OSS 2.x `/metrics`** endpoint: + +```sh +# HELP go_memstats_alloc_bytes_total Total number of bytes allocated, even if freed. +# TYPE go_memstats_alloc_bytes_total counter +go_memstats_alloc_bytes_total 1.42276424e+09 +# HELP go_memstats_buck_hash_sys_bytes Number of bytes used by the profiling bucket hash table. +# TYPE go_memstats_buck_hash_sys_bytes gauge +go_memstats_buck_hash_sys_bytes 5.259247e+06 +# HELP task_executor_run_latency_seconds Records the latency between the time the run was due to run and the time the task started execution, by task type +# TYPE task_executor_run_latency_seconds histogram +task_executor_run_latency_seconds_bucket{task_type="system",le="0.25"} 4413 +task_executor_run_latency_seconds_bucket{task_type="system",le="0.5"} 11901 +task_executor_run_latency_seconds_bucket{task_type="system",le="1"} 12565 +task_executor_run_latency_seconds_bucket{task_type="system",le="2.5"} 12823 +task_executor_run_latency_seconds_bucket{task_type="system",le="5"} 12844 +task_executor_run_latency_seconds_bucket{task_type="system",le="10"} 12864 +task_executor_run_latency_seconds_bucket{task_type="system",le="+Inf"} 74429 +task_executor_run_latency_seconds_sum{task_type="system"} 4.256783538679698e+11 +task_executor_run_latency_seconds_count{task_type="system"} 74429 +# HELP task_executor_run_duration The duration in seconds between a run starting and finishing. +# TYPE task_executor_run_duration summary +task_executor_run_duration{taskID="00xx0Xx0xx00XX0x0",task_type="threshold",quantile="0.5"} 5.178160855 +task_executor_run_duration{taskID="00xx0Xx0xx00XX0x0",task_type="threshold",quantile="0.9"} 5.178160855 +task_executor_run_duration{taskID="00xx0Xx0xx00XX0x0",task_type="threshold",quantile="0.99"} 5.178160855 +task_executor_run_duration_sum{taskID="00xx0Xx0xx00XX0x0",task_type="threshold"} 2121.9758301650004 +task_executor_run_duration_count{taskID="00xx0Xx0xx00XX0x0",task_type="threshold"} 570 +``` + +#### Resulting line protocol +``` +go_memstats_alloc_bytes_total counter=1.42276424e+09 +go_memstats_buck_hash_sys_bytes gauge=5.259247e+06 +task_executor_run_latency_seconds,task_type=system 0.25=4413,0.5=11901,1=12565,2.5=12823,5=12844,10=12864,+Inf=74429,sum=4.256783538679698e+11,count=74429 +task_executor_run_duration,taskID=00xx0Xx0xx00XX0x0,task_type=threshold 0.5=5.178160855,0.9=5.178160855,0.99=5.178160855,sum=2121.9758301650004,count=570 +``` + +{{< expand-wrapper >}} +{{% expand "View version 1 tables when queried from InfluxDB" %}} +| _time | _measurement | _field | _value | +| :------------------------ | :---------------------------- | :------ | -----------: | +| {{< flux/current-time >}} | go_memstats_alloc_bytes_total | counter | 1422764240.0 | + +| _time | _measurement | _field | _value | +| :------------------------ | :------------------------------ | :----- | --------: | +| {{< flux/current-time >}} | go_memstats_buck_hash_sys_bytes | gauge | 5259247.0 | + +| _time | _measurement | task_type | _field | _value | +| :------------------------ | :-------------------------------- | :-------- | :----- | -----: | +| {{< flux/current-time >}} | task_executor_run_latency_seconds | system | 0.25 | 4413.0 | + +| _time | _measurement | task_type | _field | _value | +| :------------------------ | :-------------------------------- | :-------- | :----- | ------: | +| {{< flux/current-time >}} | task_executor_run_latency_seconds | system | 0.5 | 11901.0 | + +| _time | _measurement | task_type | _field | _value | +| :------------------------ | :-------------------------------- | :-------- | :----- | ------: | +| {{< flux/current-time >}} | task_executor_run_latency_seconds | system | 1 | 12565.0 | + +| _time | _measurement | task_type | _field | _value | +| :------------------------ | :-------------------------------- | :-------- | :----- | ------: | +| {{< flux/current-time >}} | task_executor_run_latency_seconds | system | 2.5 | 12823.0 | + +| _time | _measurement | task_type | _field | _value | +| :------------------------ | :-------------------------------- | :-------- | :----- | ------: | +| {{< flux/current-time >}} | task_executor_run_latency_seconds | system | 5 | 12844.0 | + +| _time | _measurement | task_type | _field | _value | +| :------------------------ | :-------------------------------- | :-------- | :----- | ------: | +| {{< flux/current-time >}} | task_executor_run_latency_seconds | system | +Inf | 74429.0 | + +| _time | _measurement | task_type | _field | _value | +| :------------------------ | :-------------------------------- | :-------- | :----- | ----------------: | +| {{< flux/current-time >}} | task_executor_run_latency_seconds | system | sum | 425678353867.9698 | + +| _time | _measurement | task_type | _field | _value | +| :------------------------ | :-------------------------------- | :-------- | :----- | -----: | +| {{< flux/current-time >}} | task_executor_run_latency_seconds | system | count | 74429.0 | + +| _time | _measurement | task_type | _field | _value | +| :------------------------ | :------------------------- | :-------- | :----- | ----------: | +| {{< flux/current-time >}} | task_executor_run_duration | threshold | 0.5 | 5.178160855 | + +| _time | _measurement | task_type | _field | _value | +| :------------------------ | :------------------------- | :-------- | :----- | ----------: | +| {{< flux/current-time >}} | task_executor_run_duration | threshold | 0.9 | 5.178160855 | + +| _time | _measurement | task_type | _field | _value | +| :------------------------ | :------------------------- | :-------- | :----- | ----------: | +| {{< flux/current-time >}} | task_executor_run_duration | threshold | 0.99 | 5.178160855 | + +| _time | _measurement | task_type | _field | _value | +| :------------------------ | :------------------------- | :-------- | :----- | -----------------: | +| {{< flux/current-time >}} | task_executor_run_duration | threshold | sum | 2121.9758301650004 | + +| _time | _measurement | task_type | _field | _value | +| :------------------------ | :------------------------- | :-------- | :----- | -----: | +| {{< flux/current-time >}} | task_executor_run_duration | threshold | count | 570.0 | +{{% /expand %}} +{{< /expand-wrapper >}} + +## Metrics version 2 + +- **_time**: timestamp +- **_measurement**: `prometheus` +- **_field**: [Prometheus metric name](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels) + _(`_bucket` is trimmed from histogram metric names)_ +- **_value**: [Prometheus metric value](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels) +- **url**: URL metrics were scraped from +- **tags**: A tag for each [Prometheus label](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels). + The label name is the tag key and the label value is the tag value. + +### Example Prometheus query results +The following are example Prometheus metrics scraped from the **InfluxDB OSS 2.x `/metrics`** endpoint: + +```sh +# HELP go_memstats_alloc_bytes_total Total number of bytes allocated, even if freed. +# TYPE go_memstats_alloc_bytes_total counter +go_memstats_alloc_bytes_total 1.42276424e+09 +# HELP go_memstats_buck_hash_sys_bytes Number of bytes used by the profiling bucket hash table. +# TYPE go_memstats_buck_hash_sys_bytes gauge +go_memstats_buck_hash_sys_bytes 5.259247e+06 +# HELP task_executor_run_latency_seconds Records the latency between the time the run was due to run and the time the task started execution, by task type +# TYPE task_executor_run_latency_seconds histogram +task_executor_run_latency_seconds_bucket{task_type="system",le="0.25"} 4413 +task_executor_run_latency_seconds_bucket{task_type="system",le="0.5"} 11901 +task_executor_run_latency_seconds_bucket{task_type="system",le="1"} 12565 +task_executor_run_latency_seconds_bucket{task_type="system",le="2.5"} 12823 +task_executor_run_latency_seconds_bucket{task_type="system",le="5"} 12844 +task_executor_run_latency_seconds_bucket{task_type="system",le="10"} 12864 +task_executor_run_latency_seconds_bucket{task_type="system",le="+Inf"} 74429 +task_executor_run_latency_seconds_sum{task_type="system"} 4.256783538679698e+11 +task_executor_run_latency_seconds_count{task_type="system"} 74429 +# HELP task_executor_run_duration The duration in seconds between a run starting and finishing. +# TYPE task_executor_run_duration summary +task_executor_run_duration{taskID="00xx0Xx0xx00XX0x0",task_type="threshold",quantile="0.5"} 5.178160855 +task_executor_run_duration{taskID="00xx0Xx0xx00XX0x0",task_type="threshold",quantile="0.9"} 5.178160855 +task_executor_run_duration{taskID="00xx0Xx0xx00XX0x0",task_type="threshold",quantile="0.99"} 5.178160855 +task_executor_run_duration_sum{taskID="00xx0Xx0xx00XX0x0",task_type="threshold"} 2121.9758301650004 +task_executor_run_duration_count{taskID="00xx0Xx0xx00XX0x0",task_type="threshold"} 570 +``` + +#### Resulting line protocol +{{< keep-url >}} +``` +prometheus,url=http://localhost:8086/metrics go_memstats_alloc_bytes_total=1.42276424e+09 +prometheus,url=http://localhost:8086/metrics go_memstats_buck_hash_sys_bytes=5.259247e+06 +prometheus,url=http://localhost:8086/metrics,task_type=system,le=0.25 task_executor_run_latency_seconds=4413 +prometheus,url=http://localhost:8086/metrics,task_type=system,le=0.5 task_executor_run_latency_seconds=11901 +prometheus,url=http://localhost:8086/metrics,task_type=system,le=1 task_executor_run_latency_seconds=12565 +prometheus,url=http://localhost:8086/metrics,task_type=system,le=2.5 task_executor_run_latency_seconds=12823 +prometheus,url=http://localhost:8086/metrics,task_type=system,le=5 task_executor_run_latency_seconds=12844 +prometheus,url=http://localhost:8086/metrics,task_type=system,le=10 task_executor_run_latency_seconds=12864 +prometheus,url=http://localhost:8086/metrics,task_type=system,le=+Inf task_executor_run_latency_seconds=74429 +prometheus,url=http://localhost:8086/metrics,task_type=system task_executor_run_latency_seconds_sum=4.256783538679698e+11 +prometheus,url=http://localhost:8086/metrics,task_type=system task_executor_run_latency_seconds_count=74429 +prometheus,url=http://localhost:8086/metrics,taskID=00xx0Xx0xx00XX0x0,task_type=threshold quantile=0.5 task_executor_run_duration=5.178160855 +prometheus,url=http://localhost:8086/metrics,taskID=00xx0Xx0xx00XX0x0,task_type=threshold quantile=0.9 task_executor_run_duration=5.178160855 +prometheus,url=http://localhost:8086/metrics,taskID=00xx0Xx0xx00XX0x0,task_type=threshold quantile=0.99 task_executor_run_duration=5.178160855 +prometheus,url=http://localhost:8086/metrics,taskID=00xx0Xx0xx00XX0x0,task_type=threshold task_executor_run_duration_sum=2121.9758301650004 +prometheus,url=http://localhost:8086/metrics,taskID=00xx0Xx0xx00XX0x0,task_type=threshold task_executor_run_duration_count=570 +``` + +{{< expand-wrapper >}} +{{% expand "View version 2 tables when queried from InfluxDB" %}} +| _time | _measurement | url | _field | _value | +| :------------------------ | :----------- | :---------------------------- | :---------------------------- | -----------: | +| {{< flux/current-time >}} | prometheus | http://localhost:8086/metrics | go_memstats_alloc_bytes_total | 1422764240.0 | + +| _time | _measurement | url | _field | _value | +| :------------------------ | :----------- | :---------------------------- | :------------------------------ | --------: | +| {{< flux/current-time >}} | prometheus | http://localhost:8086/metrics | go_memstats_buck_hash_sys_bytes | 5259247.0 | + +| _time | _measurement | task_type | url | le | _field | _value | +| :------------------------ | :----------- | :-------- | :---------------------------- | :--- | :-------------------------------- | -----: | +| {{< flux/current-time >}} | prometheus | system | http://localhost:8086/metrics | 0.25 | task_executor_run_latency_seconds | 4413 | + +| _time | _measurement | task_type | url | le | _field | _value | +| :------------------------ | :----------- | :-------- | :---------------------------- | :-- | :-------------------------------- | -----: | +| {{< flux/current-time >}} | prometheus | system | http://localhost:8086/metrics | 0.5 | task_executor_run_latency_seconds | 11901 | + +| _time | _measurement | task_type | url | le | _field | _value | +| :------------------------ | :----------- | :-------- | :---------------------------- | :-- | :-------------------------------- | -----: | +| {{< flux/current-time >}} | prometheus | system | http://localhost:8086/metrics | 1 | task_executor_run_latency_seconds | 12565 | + +| _time | _measurement | task_type | url | le | _field | _value | +| :------------------------ | :----------- | :-------- | :---------------------------- | :-- | :-------------------------------- | -----: | +| {{< flux/current-time >}} | prometheus | system | http://localhost:8086/metrics | 2.5 | task_executor_run_latency_seconds | 12823 | + +| _time | _measurement | task_type | url | le | _field | _value | +| :------------------------ | :----------- | :-------- | :---------------------------- | :-- | :-------------------------------- | -----: | +| {{< flux/current-time >}} | prometheus | system | http://localhost:8086/metrics | 5 | task_executor_run_latency_seconds | 12844 | + +| _time | _measurement | task_type | url | le | _field | _value | +| :------------------------ | :----------- | :-------- | :---------------------------- | :--- | :-------------------------------- | -----: | +| {{< flux/current-time >}} | prometheus | system | http://localhost:8086/metrics | +Inf | task_executor_run_latency_seconds | 74429 | + +| _time | _measurement | task_type | url | _field | _value | +| :------------------------ | :----------- | :-------- | :---------------------------- | :------------------------------------ | ----------------: | +| {{< flux/current-time >}} | prometheus | system | http://localhost:8086/metrics | task_executor_run_latency_seconds_sum | 425678353867.9698 | + +| _time | _measurement | task_type | url | _field | _value | +| :------------------------ | :----------- | :-------- | :---------------------------- | :-------------------------------------- | -----: | +| {{< flux/current-time >}} | prometheus | system | http://localhost:8086/metrics | task_executor_run_latency_seconds_count | 74429 | + +| _time | _measurement | task_type | taskID | url | quantile | _field | _value | +| :------------------------ | :----------- | :-------- | :---------------- | :---------------------------- | :------- | :------------------------- | ----------: | +| {{< flux/current-time >}} | prometheus | threshold | 00xx0Xx0xx00XX0x0 | http://localhost:8086/metrics | 0.5 | task_executor_run_duration | 5.178160855 | + +| _time | _measurement | task_type | taskID | url | quantile | _field | _value | +| :------------------------ | :----------- | :-------- | :---------------- | :---------------------------- | :------- | :------------------------- | ----------: | +| {{< flux/current-time >}} | prometheus | threshold | 00xx0Xx0xx00XX0x0 | http://localhost:8086/metrics | 0.9 | task_executor_run_duration | 5.178160855 | + +| _time | _measurement | task_type | taskID | url | quantile | _field | _value | +| :------------------------ | :----------- | :-------- | :---------------- | :---------------------------- | :------- | :------------------------- | ----------: | +| {{< flux/current-time >}} | prometheus | threshold | 00xx0Xx0xx00XX0x0 | http://localhost:8086/metrics | 0.99 | task_executor_run_duration | 5.178160855 | + +| _time | _measurement | task_type | taskID | url | _field | _value | +| :------------------------ | :----------- | :-------- | :---------------- | :---------------------------- | :----------------------------- | -----------------: | +| {{< flux/current-time >}} | prometheus | threshold | 00xx0Xx0xx00XX0x0 | http://localhost:8086/metrics | task_executor_run_duration_sum | 2121.9758301650004 | + +| _time | _measurement | task_type | taskID | url | _field | _value | +| :------------------------ | :----------- | :-------- | :---------------- | :---------------------------- | :------------------------------- | -----: | +| {{< flux/current-time >}} | prometheus | threshold | 00xx0Xx0xx00XX0x0 | http://localhost:8086/metrics | task_executor_run_duration_count | 570 | +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/influxdb/v2.1/reference/release-notes/_index.md b/content/influxdb/v2.1/reference/release-notes/_index.md new file mode 100644 index 0000000000..c010bc0d49 --- /dev/null +++ b/content/influxdb/v2.1/reference/release-notes/_index.md @@ -0,0 +1,12 @@ +--- +title: Release notes +description: Find important information about what's included in new versions of InfluxData products. +menu: + influxdb_2_1_ref: + name: Release notes +weight: 1 +--- + +Find important information about what's included in new versions of our products: + +{{< children >}} diff --git a/content/influxdb/v2.1/reference/release-notes/influx-cli.md b/content/influxdb/v2.1/reference/release-notes/influx-cli.md new file mode 100644 index 0000000000..6e8dff1ed6 --- /dev/null +++ b/content/influxdb/v2.1/reference/release-notes/influx-cli.md @@ -0,0 +1,107 @@ +--- +title: influx CLI release notes +description: Important changes and and what's new in each version of the influx command line interface (CLI). +weight: 103 +menu: + influxdb_2_1_ref: + parent: Release notes + name: influx CLI +--- + +## v2.2.0 [2021-10-21] + +This release includes three new features and bug fixes. + +## Features + +This release makes it easier to create API tokens with the `influx` CLI, adds support for viewing more than 20 buckets using `influx bucket list`, and adds a shorthand flag for bucket (`-b`) to `influx delete`. + +{{% oss-only %}} + +### Create an Operator token in the influx CLI + +Add the ability to use the `influx` CLI to [create an Operator token](/influxdb/v2.0/security/tokens/#operator-token) with read and write permissions to all resources in all organizations available in InfluxDB. (Note, this is the same permissions generated for the initial token created by `influx setup` or `influxd upgrade`.) + +{{% /oss-only %}} + +### Create an All-Access token in the influx CLI + +Add the ability to use the `influx` CLI to [create an All-Access API token](/influxdb/cloud/security/tokens/create-token/#create-a-token-using-the-influx-cli) with read and write permissions to all resources in an organization. + +### View more buckets in the influx CLI + +Update [`influx bucket list`](/influxdb/cloud/reference/cli/influx/bucket/list/) with pagination to support displaying more than 20 buckets. By default, buckets are fetched in batches of 20; set `--page-size` to override this default value. You may also limit the total number of buckets to display with `--limit` (by default, there's no limit). + +### New bucket shorthand for influx delete + +Add the shorthand flag `-b` for `--bucket` to [`influx delete`](/influxdb/cloud/reference/cli/influx/delete/). + +## Bug fixes + +- Detect and warn when the Operator token is changed using `influx restore` (either setting a new `--active` config or updating the `INFLUX_TOKEN` variable). +- Set newly-created connection configuration as active in `influx setup`. +- Embed timezone data into Windows builds to avoid errors. + +## v2.1.1 [2021-09-24] + +## Go version + +Upgrade to Go 1.17. + +## Bug fixes + +- Fix shell completion for top-level `influx` commands. +- Make global `--http-debug` flag visible in help text. +- Don't set empty strings for IDs in permission resources. +- Detect and error out on incorrect positional arguments. +- Respect value of `--host` flag when writing CLI configs in `setup`. + +## v2.1.0 [2021-07-29] + +## New repository + +This is the initial release of the `influx` CLI from the `influxdata/influx-cli` GitHub repository. + +## Breaking changes + +### `influx write` skip-header parsing + +To simplify the CLI parser, the `write` command no longer supports `--skipHeader` +as short-hand for `--skipHeader 1`. + +### Stricter input validation for `influx template` commands + +The `apply`, `export`, and `stacks` commands now raise errors when CLI options fail to parse instead of silently discarding bad inputs. +This change was made to help users debug when their commands fail to execute as expected. + +### Server-side template summarization and validation + +The `template` and `template validate` commands now use an API request to the server to perform their logic, instead of performing the work on the client-side. +Offline summarization and validation is no longer supported. +This change was made to avoid significant code duplication between `influxdb` and `influx CLI`, and to allow server-side template logic to evolve without requiring coordinated CLI changes. + +### `influx stacks --json` output conventions + +The output of `influx stacks --json` previously used an UpperCamelCase naming convention for most keys. +The command now uses lowerCamelCase consistently for all objects keys, matching the schema returned by the API. + +## Features + +- Add global `--http-debug` flag to all `influx` commands to help inspect communication with InfluxDB servers. +- Update [`bucket create`](/influxdb/cloud/reference/cli/influx/bucket/create/) to allow setting a schema type. +- Update [`bucket list`](/influxdb/cloud/reference/cli/influx/bucket/list/) to display schema types. +- Bind [`--skip-verify`](/influxdb/cloud/reference/cli/influx/org/members/add/#flags) flag to the `INFLUX_SKIP_VERIFY` environment variable. +- (InfluxDB Cloud only) Add [`buck +- (InfluxDB OSS only) Updates to `backup` and `restore`: + - Reimplement [`backup`](/influxdb/cloud/reference/cli/influx/backup/) to support downloading embedded SQL store from InfluxDB 2.0 or later. + - Add [`--compression`](/influxdb/v2.0/reference/cli/influx/backup/_index.md) flag to support GZIP compression of downloaded files. + - Reimplement `restore` to support uploading embedded SQL store from InfluxDB v2.1.x. +- (InfluxDB OSS only) Add [`--password`](/influxdb/cloud/reference/cli/influx/user/password/) flag to `user password` command to allow bypassing interactive prompt. + +## Bug fixes + +- Fix interactive password collection and color rendering in PowerShell. +- `org members list` no longer hangs on organizations with more than 10 members. +- Detect and warn when inputs to `write` contain standalone CR characters. +- `dashboards` command now accepts `--org` flag, or falls back to default org in config. +- Return a consistent error when responses fail to decode, including hints for OSS-only and Cloud-only commands. diff --git a/content/influxdb/v2.1/reference/release-notes/influxdb.md b/content/influxdb/v2.1/reference/release-notes/influxdb.md new file mode 100644 index 0000000000..8a5a17620a --- /dev/null +++ b/content/influxdb/v2.1/reference/release-notes/influxdb.md @@ -0,0 +1,1626 @@ +--- +title: InfluxDB v2.1 release notes +description: Important changes and what's new in each version of InfluxDB. +menu: + influxdb_2_1_ref: + name: InfluxDB + parent: Release notes +weight: 101 +--- + +## v2.1.0 [2021-11-03] + +- This release includes several new [features](#features) and [bug fixes](#bug-fixes). + +### `influx` CLI moved to separate repository + +The `influx` CLI has been moved to its own GitHub [repository](https://github.com/influxdata/influx-cli/). + +{{% warn %}} +#### `influxdb` release artifacts affected +Release artifacts produced by `influxdb` are impacted as follows: + +- Release archives (`.tar.gz` and `.zip`) **no longer contain** the `influx` binary. +- The `influxdb2` package (`.deb` and `.rpm`) **no longer contains** the `influx` binary. Instead, the package declares a recommended dependency on the new `influxdb2-cli` package. +- The `quay.io/influxdb/influxdb` image **no longer contains** the `influx` binary. We recommend migrating to the `influxdb` image hosted on [DockerHub](https://hub.docker.com/_/influxdb). +{{% /warn %}} + +#### Find supported `influx` CLI commands + +With this change, versions of the `influx` CLI and InfluxDB server (`influxd`) are not guaranteed to exactly match. To check the version of the `influxd` server, see `influxd version` in `influx` CLI or use the `/health` endpoint of your InfluxDB server. + +{{% note %}} +The [`influx` CLI documentation](/influxdb/v2.1/reference/cli/influx/) has been updated to reflect which `influx` CLI commands work with which versions of InfluxDB. +{{% /note %}} + +### Features + +This release includes the following new features: + +- [Notebooks, annotations, and visualization updates](#notebooks-annotations-and-visualization-updates) +- [API](#api) and [CLI](#cli) updates +- Support for latest [Flux](#flux) and [Telegraf](#telegraf) releases +- Updates to the [InfluxQL](#influxql) +- [Token](#tokens) updates +- [Flux location support](#flux-location-support) + +#### Notebooks, annotations, and visualization updates + +- Add support for [notebooks](/influxdb/v2.1/notebooks/) and [annotations](/influxdb/v2.1/visualize-data/annotations/). +- Add support for static legends to line graphs and band plots. +- Enable new dashboard auto-refresh. +- Simplify display of data for table visualizations. + +#### API + +- Add new parameters to GET [`/users`](/influxdb/v2.1/api/#operation/GetUsers) API, including: `offset`, `limit`, and `after`. +- Add the [`api/v2/backup/metadata`](/influxdb/v2.1/api/#operation/GetBackupMetadata) endpoint for backing up both key-value and SQL metadata, and the [`api/v2/restore/sql`](/influxdb/v2.1/api/#operation/GetRoutes) for restoring SQL metadata. +- Deprecated [`POST .../secrets/delete`](/influxdb/v2.1/api/#operation/PostOrgsIDSecrets). To delete a secret, use [`DELETE .../secrets/{secretID}`](/influxdb/v2.1/api/#operation/DeleteOrgsIDSecretsID). + +#### CLI + +##### influxd configuration + +Added several new configuration options to [`influxd`](/influxdb/v2.1/reference/cli/influxd/): + +- Add `influxd recovery` command to let you create a recovery [Operator token](/influxdb/v2.1/security/tokens/#operator-token). +- Add `--sqlite-path` flag for specifying a user-defined path to the SQLite database file. +- Add `--storage-wal-max-concurrent-writes` flag to enable tuning memory pressure under heavy write load. +- Add `--storage-wal-max-write-delay` flag to prevent deadlocks when the WAL is overloaded with concurrent writes. +- Add `--storage-write-timeout` flag to set write request timeouts. +- Add `--storage-no-validate-field-size` flag to disable enforcement of max field size. +- Update `--store` flag to work with string values disk or memory. Memory continues to store metadata in-memory for testing; disk persists metadata to disk via bolt and SQLite. + +For more information, see [InfluxDB configuration options](/influxdb/v2.1/reference/config-options/). + +##### influxd inspect + +Ported the following [`influxd inspect`](/influxdb/v2.1/reference/cli/influxd/inspect/) commands from InfluxDB 1.x: + +- [influxd inspect build-tsi](/influxdb/v2.1/reference/cli/influxd/inspect/build-tsi/) +- [influxd inspect delete-tsm](/influxdb/v2.1/reference/cli/influxd/inspect/delete-tsm/) +- [influxd inspect dump-tsi](/influxdb/v2.1/reference/cli/influxd/inspect/dump-tsi/) +- [influxd inspect dump-tsm](/influxdb/v2.1/reference/cli/influxd/inspect/dump-tsm/) +- [influxd inspect dump-wal](/influxdb/v2.1/reference/cli/influxd/inspect/dump-wal/) +- [influxd inspect report-tsi](/influxdb/v2.1/reference/cli/influxd/inspect/report-tsi/) +- [influxd inspect report-tsm](/influxdb/v2.1/reference/cli/influxd/inspect/report-tsm/) +- [influxd inspect verify-seriesfile](/influxdb/v2.1/reference/cli/influxd/inspect/verify-seriesfile/) +- [influxd inspect verify-tombstone](/influxdb/v2.1/reference/cli/influxd/inspect/verify-tombstone/) +- [influxd inspect verify-tsm](/influxdb/v2.1/reference/cli/influxd/inspect/verify-tsm/) +- [influxd inspect verify-wal](/influxdb/v2.1/reference/cli/influxd/inspect/verify-wal/) + +##### influxd downgrade + +Added the [influxd downgrade command](/influxdb/v2.1/reference/cli/influxd/downgrade/) +to migrate InfluxDB key-value metadata schemas to earlier 2.x versions when necessary. + +#### Flux + +- Update to [Flux v0.139.0](/flux/v0.x/release-notes/#v01390-2021-11-01). +- Enable writing to remote hosts using the Flux [`to()`](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/to/) and [`experimental.to()`](/{{< latest "flux" >}}/v0.x/stdlib/experimental/to/) functions. +- Flux now supports locations that dynamically modify time offsets based on your specified timezone. You can also specify fixed time offsets relative to UTC. +- Perform [bitwise operations](/{{< latest "flux" >}}/stdlib/experimental/bitwise/) + on integers and unsigned integers. +- [Query](/{{< latest "flux" >}}/query-data/sql/vertica/) and + [write to Vertica](/{{< latest "flux" >}}/query-data/sql/vertica/) SQL databases. +- Add the [`hex` package](/{{< latest "flux" >}}/stdlib/contrib/bonitoo-io/hex/) + for working with hexadecimal string values. + +#### InfluxQL + +- `SHOW MEASUREMENTS ON` now supports database and retention policy wildcards. For example, `SHOW MEASUREMENTS ON *.*` to show all databases and `SHOW MEASUREMENTS ON .*` to show all retention policies. +- Add hyper log operators `merge_hll`, `sum_hll`, and `count_hll` in InfluxQL to optimize series iteration. (`count_hll` optimizes queries that can be answered without inspecting TSM data.) + +#### Telegraf + +- Add the following new [Telegraf plugins](https://docs.influxdata.com/telegraf/v1.20/plugins/) to the Load Data page: + - Alibaba (Aliyun) CloudMonitor Service Statistics (`aliyuncms`) + - AMD ROCm System Management Interface (SMI) (`amd_rocm_smi`) + - Counter-Strike: Global Offensive (CS:GO) (`csgo`) + - Directory Monitoring (`directory_monitor`) + - Intel Data Plane Development Kit (DPDK) (`dpdk`) + - Elasticsearch Query (`elasticsearch_query`) + - Internet Speed Monitor (`internet_speed`) + - KNX (`knx_listener`) + - Mdstat (`mdstat`) + - Netstat (`netstat`) + - NFS Client (`nfsclient`) + - OpenTelemetry (`opentelemetry`) + - RavenDB (`ravendb`) + - SQL (`sql`) + - Trig (`trig`) + - Twemproxy (`twemproxy`) + +For more information about each plugin, see [Telegraf plugins](/telegraf/v1.20/plugins/), and search for the plugin name. + +#### Tokens + +- Add support for standard Bearer token syntax. Now you can specify token credentials as: `Authorization: Bearer xxxxxxxx`. +- If restoring a backup overwrites the Operator token, the new token value is returned. + +### Bug fixes + +- Log API errors to server logs and tell clients to check the server logs for the error message. +- Fix pagination for GET [`/buckets`](/influxdb/v2.1/api/#operation/GetBuckets) API when displaying results. Previously, pagination was broken if a request included both an `org` filter AND the `after` request parameter. Also corrects `descending` parameter to sort when an `org` filter is used and saved. +- Sync series segment to disk after writing. +- Do not allow shard creation to create overlapping shards. +- Don't drop shard group durations when upgrading InfluxDB. + +## v2.0.9 [2021-09-27] + +This release includes several new [features](#features) and [bug fixes](#bug-fixes). + +### Features + +New features include: + +- [API updates](#api-updates) +- [Flux updates](#flux-updates) +- [Performance enhancements](#performance-enhancements) + +#### API updates + +- Add a new route `/api/v2/resources` that returns a list of known resources to the platform, including the following resource types. Makes it easier to update all-access tokens with current resources: + + - `AuthorizationsResourceType` + - `BucketsResourceType` + - `ChecksResourceType` + - `DashboardsResourceType` + - `DBRPResourceType` + - `DocumentsResourceType` + - `LabelsResourceType` + - `NotificationEndpointResourceType` + - `NotificationRuleResourceType` + - `OrgsResourceType` + - `ScraperResourceType` + - `SecretsResourceType` + - `SourcesResourceType` + - `TasksResourceType` + - `TelegrafsResourceType` + - `UsersResourceType` + - `VariablesResourceType` + - `ViewsResourceType` + +#### Flux updates + +- Update to [Flux v0.130.0](/flux/v0.x/release-notes/#v01300-2021-09-15). +- Add support for [`influxdb.cardinality()`](/flux/v0.x/stdlib/influxdata/influxdb/cardinality/) function. +- Operational improvements: + - Add logging to Flux end-to-end tests (`TestFluxEndToEnd`) to help diagnose test failures. + - Add `--flux-log-enabled` option to [`influxd`](/influxdb/v2.1/reference/config-options/) to show detailed logs for Flux queries. + +#### Performance enhancements + +- Optimize series iteration for queries that can be answered without inspecting TSM data. +- Optimize queries with predicates that contain multiple measurements. + +### Bug fixes + +This release includes the following bug fixes and updates: + +- [API fix](#api-fix) +- [Dependency update](#dependency-update) +- [Error updates](#error-updates) +- [Limit update](#limit-update) +- [Miscellaneous operational fixes](#miscellaneous-operational-fixes) +- [Task updates](#task-updates) +- [Version maintenance](#version-maintenance) + +#### API fix + +- Correctly filter requests to `/api/v2/authorizations` by `org` and `user` parameters. + +#### Dependency update + +- Include `curl` as a dependency in `influxdb2` packages. + +#### Errors updates + +- Add message to set the Flux `content-type` when a query fails to parse as JSON. +- Discard excessive errors over `DefaultMaxSavedErrors (100)` to prevent out-of-memory crashes. +- Upgrade `golang.org/x/sys` to avoid panics on macs. + +#### Limit update + +- Implement hard limit on field size (`MaxFieldValueLength = 1048576`) while parsing line protocol. + +#### Miscellaneous operational fixes + +- Resolve the compaction queue stats flutter. +- Ensure the TSI index compacts log files that meet one of the following criteria: + - Log file hasn't been updated (no new series have been added to the shard) for 4 (or more) hours (to change this duration, specify a new [`storage-compact-full-write-cold-duration`](/influxdb/v2.1/reference/config-options/#storage-compact-full-write-cold-duration)) + - Log file is one (or more) megabytes (to update this size, specify a new [`storage-max-index-log-file-size`](/influxdb/v2.1/reference/config-options/#storage-max-index-log-file-size)) +- Repair bad port dropping return value names. +- Use consistent path separator in permission string representation. +- (Windows only) Copy snapshot files being backed up. + +#### Task updates + +- Updating an inactive task no longer schedules it. Thanks @raffs! +- Preserve comments in Flux queries when saving task definitions. + +#### Version maintenance + +- Fix `X-Influxdb-Build` and `X-Influxdb-Version` response header at `/ping`. +- Upgrade `influxql` to latest version and fix predicate handling for `SHOW TAG VALUES` meta queries. + +## v2.0.8 [2021-08-13] + +{{% warn %}} #### Upcoming changes to influx CLI packaging + +Beginning in InfluxDB 2.1, the `influx` CLI will no longer be packaged with the release. Future versions of `influx` CLI will be released from the [influx-cli](https://github.com/influxdata/influx-cli) repository. + +To adopt the new, separate `influx` CLI early, download the latest release from [GitHub](https://github.com/influxdata/influx-cli/releases/tag/v2.1.0) or from the [InfluxData Downloads portal](https://portal.influxdata.com/downloads/). +{{% /warn %}} + +### Go version + +- Upgrade to Go 1.16. **Requires macOS Sierra 10.12 or later to run.** + +### Features + +- Add `--ui-disabled` option to `influxd` to support running with the UI disabled. +- Telemetry improvements: Do not record telemetry data for non-existent paths; replace invalid static asset paths with a slug. +- Upgrade to Flux v0.124.0. +- Upgrade to UI v2.0.8. +- Upgrade `flux-lsp-browser` to v0.5.53. + +### Bug fixes + +- Rename ARM RPM packages with yum-compatible names. +- Upgrade to latest version of `influxdata/cron` so that tasks can be created with interval of `every: 1w`. +- Avoid rewriting `fields.idx` unnecessarily. +- Do not close connection twice in DigestWithOptions. +- Remove incorrect optimization for group-by. +- Return an error instead of panicking when InfluxQL statement rewrites fail. +- Migrate restored KV snapshots to latest schema before using them. +- Specify which fields are missing when rejecting an incomplete onboarding request. +- Ensure `systemd` unit blocks on startup until HTTP endpoint is ready. +- Fix display and parsing of `influxd upgrade` CLI prompts in PowerShell. +- Removed unused `chronograf-migator` package and chronograf API service, and updated various "chronograf" references. +- Fix display and parsing of interactive `influx` CLI prompts in PowerShell. +- Upgrade to `golang-jwt` 3.2.1. +- Prevent silently dropped writes when there are overlapping shards. +- Invalid requests to `/api/v2` subroutes now return 404 instead of a list of links. +- Flux meta queries for `_field` take fast path if `_measurement` is the only predicate. +- Copy names from mmapped memory before closing iterator. + +## v2.0.7 [2021-06-04] + +### Features + +- Optimize [`table.fill()`](/{{< latest "flux" >}}/stdlib/experimental/table/fill/) + execution within Flux aggregate windows. +- Upgrade Flux to [v0.117.0](/{{< latest "flux" >}}/release-notes/#v01171-2021-06-01). +- Upgrade UI to v2.0.7. +- Upgrade `flux-lsp-browser` to v0.5.47. + +### Bug Fixes + +- Fix query range calculation (off by one) over partially compacted data. +- Deprecate the unsupported `PostSetupUser` API. +- Add limits to the `/api/v2/delete` endpoint for start and stop times with error messages. +- Add logging to NATS streaming server to help debug startup failures. +- Accept `--input` instead of a positional argument in `influx restore`. +- Print error instead of panicking when `influx restore` fails to find backup manifests. +- Set last-modified time of empty shard directory to the directory's last-modified time, instead of the Unix epoch. +- Remove deadlock in `influx org members list` when an organization has greater than 10 members. +- Replace telemetry file name with slug for `ttf`, `woff`, and `eot` files. +- Enable use of absolute path for `--upgrade-log` when running `influxd upgrade` on Windows. +- Make InfluxQL meta queries respect query timeouts. + +--- + +## v2.0.6 General Availability [2021-04-29] + +### Bug Fixes +- Ensure query configuration written by `influxd upgrade` is valid. +- Set `query-concurrency` and `query-queue-size` configuration option defaults + to `0` to avoid validation failures when upgrading users. +- Correctly validate when `query-concurrency` is `0` and `query-queue-size` is + greater than `0`. + +## v2.0.5 General Availability [2021-04-27] + +{{% warn %}} +InfluxDB v2.0.5 introduced a defect that prevents users from successfully upgrading +from InfluxDB 1.x to 2.0 using the `influxd upgrade` command or Docker. +To [automatically upgrade from 1.x to 2.0](/influxdb/v2.1/upgrade/v1-to-v2/automatic-upgrade/) +with the `influxd upgrade` command or [with Docker](/influxdb/v2.1/upgrade/v1-to-v2/docker/), +use [InfluxDB v2.0.6](#v206-general-availability-2021-04-29). +{{% /warn %}} + +### Windows Support +This release includes our initial Windows preview build. + +### Breaking Changes + +#### /debug/vars removed +Prior to this release, the `influxd` server would expose profiling information over the `/debug/vars` endpoint. +This endpoint was unauthenticated and not used by InfluxDB systems to report diagnostics. +For security and clarity, the endpoint has been removed. +Use the `/metrics` endpoint to collect system statistics. + +#### `influx transpile` removed +The `transpile` command has been removed. Send InfluxQL requests directly to the server via the `/api/v2/query` +or `/query` HTTP endpoints. + +#### Default query concurrency changed +The default setting for the max number of concurrent Flux queries has been changed from 10 to unlimited (`0`). +To limit query concurrency and queue size: + +1. Set the `query-concurrency` config parameter to > 0 when running `influxd` to re-limit the maximum running query count, +2. Set the `query-queue-size` config parameter to > 0 to set the max number of queries that can be queued before the + server starts rejecting requests. + +#### Prefix for query-controller metrics changed +The prefix used for Prometheus metrics from the query controller has changed from `query_control_` to `qc_`. + +### Features +- Add [Swift client library](https://github.com/influxdata/influxdb-client-swift) + to the **Load Data** section of the InfluxDB UI. +- Add [`influx task retry-failed` command](/influxdb/v2.1/reference/cli/influx/task/retry-failed/) to rerun failed runs. +- Add [`--compression` option](/influxdb/v2.1/reference/cli/influx/write/#flags) + to the `influx write` command to support Gzip inputs. +- Add new `influxd` configuration options: + - [pprof-disabled](/influxdb/v2.1/reference/config-options/#pprof-disabled) + - [metrics-disabled](/influxdb/v2.1/reference/config-options/#metrics-disabled) + - [http-read-header-timeout](/influxdb/v2.1/reference/config-options/#http-read-header-timeout) + - [http-read-timeout](/influxdb/v2.1/reference/config-options/#http-read-timeout) + - [http-write-timeout](/influxdb/v2.1/reference/config-options/#http-write-timeout) + - [http-idle-timeout](/influxdb/v2.1/reference/config-options/#http-idle-timeout) +- Add `/debug/pprof/all` HTTP endpoint to gather all profiles at once. +- Include the InfluxDB 1.x `http.pprof-enabled` configuration option in the 2.0 configuration file generated by the [InfluxDB upgrade process](/influxdb/v2.1/upgrade/v1-to-v2/automatic-upgrade/). +- Add support for [custom shard group durations](/influxdb/v2.1/reference/cli/influx/bucket/create#create-a-bucket-with-a-custom-shard-group-duration) on buckets. +- Optimize regular expression conditions in InfluxQL subqueries. +- Update Telegraf plugins in the InfluxDB UI to include additions and changes from + [Telegraf 1.18](/telegraf/v1.18/about_the_project/release-notes-changelog/#v118-2021-3-17). +- Display task IDs in the tasks list in the InfluxDB UI. +- Write to standard output (`stdout`) when `--output-path -` is passed to [`influxd inspect export-lp`](/influxdb/v2.1/reference/cli/influxd/inspect/export-lp/). +- Add `-p, --profilers` flag to [`influx query` command](/influxdb/v2.1/reference/cli/influx/query/) + to enable [Flux profilers](/{{< latest "flux" >}}/stdlib/profiler/) on + a query executed from the `influx` CLI. +- Update InfluxDB OSS UI to match InfluxDB Cloud. +- Support disabling concurrency limits in the Flux controller. +- Replace unique resource IDs (UI assets, backup shards) with slugs to reduce + cardinality of telemetry data. +- Standardize HTTP server error log output. +- Enable InfluxDB user interface features: + - [Band visualization type](/influxdb/v2.1/visualize-data/visualization-types/band/) + - [Mosiac visualization type](/influxdb/v2.1/visualize-data/visualization-types/mosaic/) + - [Configure axis tick marks](/influxdb/v2.1/visualize-data/visualization-types/graph/#x-axis) + - Upload CSV files through the InfluxDB UI + - [Edit Telegraf configurations](/influxdb/v2.1/telegraf-configs/update/#edit-the-configuration-file-directly-in-the-ui) in the InfluxDB UI + - [Legend orientation options](/influxdb/v2.1/visualize-data/visualization-types/graph/#legend) + - [Refresh a single dashboard cell](/influxdb/v2.1/visualize-data/dashboards/control-dashboard/#refresh-a-single-dashboard-cell) +- Upgrade to **Flux v0.113.0**. + +### Bug Fixes +- Prevent "do not have an execution context" error when parsing Flux options in tasks. +- Fix swagger to match implementation of DBRPs type. +- Fix use-after-free bug in series ID iterator. +- Fix TSM and WAL segment size check to check against the local `SegmentSize`. +- Fix TSM and WAL segment size computing to correctly calculate `totalOldDiskSize`. +- Update references to the documentation site site to use current URLs. +- Fix data race in then TSM engine when inspecting tombstone statistics. +- Fix data race in then TSM cache. +- Deprecate misleading `retentionPeriodHrs` key in the onboarding API. +- Fix Single Stat graphs with thresholds crashing on negative values. +- Fix InfluxDB port in Flux function UI examples. +- Remove unauthenticated, unsupported `/debug/vars` HTTP endpoint. +- Respect 24 hour clock formats in the InfluxDB UI and add more format choices. +- Prevent "do not have an execution context" error when parsing Flux options in tasks. +- Prevent time field names from being formatted in the Table visualization. +- Log error details when `influxd upgrade` fails to migrate databases. +- Fix the cipher suite used when TLS strict ciphers are enabled in `influxd`. +- Fix parse error in UI for tag filters containing regular expression meta characters. +- Prevent concurrent access panic when gathering bolt metrics. +- Fix race condition in Flux controller shutdown. +- Reduce lock contention when adding new fields and measurements. +- Escape dots in community templates hostname regular expression. + +## v2.0.4 General Availability [2021-02-04] + +### Docker + +#### ARM64 +This release extends the Docker builds hosted in `quay.io` to support the Linux/ARM64 platform. + +#### 2.x nightly images +Prior to this release, competing nightly builds caused the nightly Docker tag to contain outdated binaries. This conflict is fixed, and the image tagged with nightly now contains 2.x binaries built from the `HEAD` of the `master` branch. + +### Breaking Changes + +#### `inmem` index option removed + +This release fully removes the `inmem` indexing option, along with the associated config options: +- `max-series-per-database` +- `max-values-per-tag` + +The startup process automatically generates replacement `tsi1` indexes for shards that need it. + +### Features + +#### `influxd` updates +- Add new [`influxd upgrade`](/influxdb/v2.1/reference/cli/influxd/upgrade/) flag `—overwrite-existing-v2` to overwrite existing files at output paths (instead of aborting). +- Add new configuration options: + - [`nats-port`](/influxdb/v2.1/reference/config-options/#nats-port) + - [`nats-max-payload-bytes`](/influxdb/v2.1/reference/config-options/#nats-max-payload-bytes) +- Add new commands: + - Add [`influxd print-config`](/influxdb/v2.1/reference/cli/influxd/print-config/) to support automated configuration inspection. + - Add [`influxd inspect export-lp`](/influxdb/v2.1/reference/cli/influxd/inspect/export-lp/) to extract data in line-protocol format. + +#### New Telegraf plugins in UI +- Update Telegraf plugins list in UI to include Beat, Intel PowerStats, and Rienmann. + +#### Performance improvements +- Promote schema and fill query optimizations to default behavior. + +#### Flux updates +- Upgrade to [Flux v0.104.0](/{{< latest "flux" >}}/release-notes/#v0-104-0-2021-02-02). +- Upgrade to `flux-lsp-browser` v0.5.31. + +### Bug Fixes + +- Standardize binary naming conventions. +- Fix configuration loading issue. +- Add Flux dictionary expressions to Swagger documetnation. +- Ensure `influxdb` service sees default environment variables when running under `init.d`. +- Remove upgrade notice from new installs. +- Ensure `config.toml` is initialized on new installs. +- Include upgrade helper script (`influxdb2-upgrade.sh`) in GoReleaser manifest. +- Prevent `influx stack update` from overwriting stack name and description. +- Fix timeout setup for `influxd` graceful shutdown. +- Require user to set password during initial user onboarding. +- Error message improvements: + - Remove duplication from task error messages. + - Improve error message shown when influx CLI can't find an `org` by name. + - Improve error message when opening BoltDB with unsupported file system options. + - Improve messages in DBRP API validation errors. +- `influxd upgrade` improvements: + - Add confirmation step with file sizes before copying data files. + - Prevent panic in `influxd upgrade` when v1 users exist but v1 config is missing. +- Fix logging initialization for storage engine. +- Don't return 500 codes for partial write failures. +- Don't leak `.tmp` files while backing up shards. +- Allow backups to complete while a snapshot is in progress. +- Fix silent failure to register CLI arguments as required. +- Fix loading when `INFLUXD_CONFIG_PATH` points to a .yml file. +- Prevent extra output row from GROUP BY crossing DST boundary. +- Update Flux functions list in UI to reflect that `v1` package was renamed to `schema`. +- Set correct `Content-Type` on v1 query responses. +- Respect the `--skip-verify` flag when running `influx query`. +- Remove blank lines from payloads sent by `influx write`. +- Fix infinite loop in Flux parser caused by invalid array expressions. +- Support creating users without initial passwords in `influx user create`. +- Fix incorrect errors when passing `--bucket-id` to `influx write`. + +## v2.0.3 General Availability [2020-12-14] + +### Breaking Changes + +#### `influxd upgrade` + +Previously, `influxd upgrade` would attempt to write upgraded `config.toml` files into the same directory as the source +`influxdb.conf` file. If this failed, a warning would be logged and `config.toml` would write into the `home` directory of the user who launched the upgrade. + +This release breaks this behavior in two ways: + +- By default, `config.toml` writes into the same directory as the Bolt DB and engine files (`~/.influxdbv2/`) +- If writing upgraded config fails, the `upgrade` process exits with an error instead of falling back to the `HOME` directory + +To override the default configuration path (`~/.influxdbv2/`), use the new `--v2-config-path` option to specify the output path to the v2 configuration file (`config.toml`). For details, see [Upgrade from InfluxDB 1.x to InfluxDB 2.0](/influxdb/v2.1/upgrade/v1-to-v2/). + +#### InfluxDB v2 packaging + +We've renamed the InfluxDB v2 DEB and RPM packages to clarify versions. The package name is now `influxdb2` and conflicts with any previous `influxdb` package (including initial 2.0.0, 2.0.1, and 2.0.2 packages). + +This release also defines v2-specific path defaults and provides [helper scripts](https://github.com/influxdata/influxdb/blob/master/scripts/influxdb2-upgrade.sh) for `influxd upgrade` and cleanup cases. + +### Features + +- Allow password to be specified as a CLI option in [`influx v1 auth create`](/influxdb/cloud/reference/cli/influx/auth/create/). +- Allow password to be specified as a CLI option in [`influx v1 auth set-password`](/influxdb/cloud/reference/cli/influx/auth/). +- Implement [delete with predicate](/influxdb/v2.1/write-data/delete-data/). +- Improve ID-related error messages for `influx v1 dbrp` commands. +- Update Flux to [v0.99.0](/{{< latest "flux" >}}/release-notes/#v0-99-0-2020-12-15). +- Update `flux-lsp-browser` to v0.5.25. +- Support for ARM64 preview build. + +### Bug Fixes + +- Don't log bodies of v1 write request bodies. +- Fix panic when writing a point with 100 or more tags. +- Fix validation of existing DB names when creating DBRP mappings. +- Enforce max value of 2147483647 on query concurrency to avoid startup panic. +- Automatically migrate existing DBRP mappings from old schema to avoid panic. +- Optimize shard lookup in groups containing only one shard. +- Always respect the `--name` option in `influx setup`. +- Allow for 0 (infinite) values for `--retention` in `influx setup`. +- Fix panic when using a `null` value as a record or array in a Flux query. + +## v2.0.2 General Availability [2020-11-19] + +### Breaking changes + +#### DBRP HTTP API now matches Swagger documentation + +Previously, the database retention policy (DBRP) mapping API did not match the swagger spec. If you're using scripts based on the previous implementation instead of the swagger spec, you'll need to either update them or use the new [DBRP CLI commands](/influxdb/v2.1/reference/cli/influx/v1/dbrp/) instead. + +### Features +- Improvements to upgrade from 1.x to 2.x: + - Warning appears if auth is not enabled in 1.x (`auth-enabled = false`), which is not an option in 2.x. For details, see [Upgrade from InfluxDB 1.x to InfluxDB 2.0](/influxdb/v2.1/upgrade/v1-to-v2/). + - `upgrade` command now checks to see if continuous queries are running and automatically exports them to a local file. +- Upgrade to [Flux v0.95.0](/{{< latest "flux" >}}/release-notes/#v0-95-0-2020-11-17). +- Upgrade `flux-lsp-browser` to v.0.5.23. +- Manage database retention policy (DBRP) mappings via CLI. See [`influx v1 dbrp`](/influxdb/v2.1/reference/cli/influx/v1/dbrp/). +- Filter task runs by time. + +### Bug Fixes +- Fixes to `influx upgrade` command: + - Remove internal subcommands from help text. + - Validate used input paths upfront. +- Add locking during TSI iteration creation. +- Fix various typos. +- Use `--skip-verify` flag for backup/restore CLI command. This is passed to the underlying HTTP client for the `BackupService` and `RestoreService` to support backup and restore on servers with self-signed certificates. +- Don't automatically print help on `influxd` errors. +- Add `SameSite=Strict` flag to session cookie. +- Ensure `SHOW DATABASES` returns a list of the unique databases only. +- Allow scraper to ignore insecure certificates on an endpoint. +- Ensure Flux reads across all shards. +- Use the associated default retention policies defined within the DBRP mapping if no retention policy is specified as part of a v1 write API call. +- Add locking during TSI iterator creation. +- Allow self-signed certificates for scraper targets. +- Bump version in `package.json` so it appears correctly. + +## v2.0.1 General Availability [2020-11-10] + +InfluxDB 2.0 general availability (GA) introduces the first **production-ready** open source version of InfluxDB 2.0. This release comprises all features and bug fixes included in prior alpha, beta, and release candidate versions. + +{{% note %}} +#### Known issues + +##### Delete with predicate API not implemented + +The delete with predicate API (`/api/v2/delete`) has not been implemented and currently returns a `501 Not implemented` message. This API will be implemented post GA. + +##### Duplicate DBRP mappings per database + +When there are multiple [DBRP mappings](/influxdb/v2.1/reference/api/influxdb-1x/dbrp/) with the same database name in InfluxDB 1.x, SHOW DATABASES incorrectly returns duplicates. +{{% /note %}} + +Highlights include: + +- Support for **upgrading to InfluxDB 2.0**: + - To upgrade **from InfluxDB 1.x**, see [Upgrade from InfluxDB 1.x to InfluxDB 2.0](/influxdb/v2.1/upgrade/v1-to-v2). + - To upgrade **from InfluxDB 2.0 beta 16 or earlier**, see [Upgrade from InfluxDB 2.0 beta to InfluxDB 2.0](/influxdb/v2.1/upgrade/v2-beta-to-v2). +- **Flux**, our powerful new functional data scripting language designed for querying, analyzing, and acting on data. This release includes [Flux v0.94.0](/{{< latest "flux" >}}/release-notes/#v0-94-0-2020-11-09). If you're new to Flux, [check out how to get started with Flux](/influxdb/v2.1/query-data/get-started/). Next, delve deeper into the [Flux standard library](/{{< latest "flux" >}}/stdlib//) reference docs and see how to [query with Flux](/influxdb/v2.1/query-data/flux/). +- Support for [InfluxDB 1.x API compatibility](/influxdb/v2.1/reference/api/influxdb-1x/). +- **Templates** and **stacks**. Discover how to [use community templates](/influxdb/v2.1/influxdb-templates/use/) and how to [manage templates with stacks](/influxdb/v2.1/influxdb-templates/stacks/). + +If you're new to InfluxDB 2.0, we recommend checking out [how to get started](/influxdb/v2.1/get-started/) and [InfluxDB key concepts](/influxdb/v2.1/reference/key-concepts/). + +## v2.0.0 [2020-11-09] + +### Features +- Improve UI for v1 `influx auth` commands. +- Upgrade to [Flux v0.94.0](/{{< latest "flux" >}}/release-notes/#v0-94-0-2020-11-10) +- Upgrade `flux-lsp-browser` to v0.5.22. +- Add [RAS Telegraf input plugin](/telegraf/v1.16/plugins//#ras). + +### Bug Fixes + +- Remove unused `security-script` option from `influx upgrade` command. +- Fix parsing of retention policy CLI arguments in `influx setup` and `influxd upgrade`. +- Create CLI configs during upgrade to v2. +- Allow write-only v1 tokens to find database retention policies (DBRPs). +- Update `v1 auth` description. +- Use `db`/`rp` naming convention when migrating databases to buckets. +- Improve help text for `influxd` and `--no-password` switch. +- Use `10` instead of `MaxInt` when rewriting query-concurrency. +- Remove bucket and mapping auto-creation from `/write` 1.x compatibility API. +- Fix misuse of `reflect.SliceHeader`. + +## v2.0.0-rc.4 [2020-11-05] + +### Features + +- Upgrade to [Flux v0.93.0](/{{< latest "flux" >}}/release-notes/#v0-93-0-2020-11-02). +- Add `influx backup` and `influx restore` CLI commands to support backing up and restoring data in InfluxDB 2.0. +- Add the `v1/authorization` package to support authorizing requests to the InfluxDB 1.x API. + +### Bug Fixes + +- Add a new `CreateUniquePhysicalNode` method, which reads and applies the plan node ID in context. Each physical node has a unique ID to support planner rules applied more than once in a query. Previously, the same node ID (hence the same dataset ID) caused the execution engine to generate undefined results. +- A cloned task is now only activated when you select **Active**. Previously, a cloned task was activated if the original task was activated. +- Reduce the `influx` binary file size. +- Isolate the `TelegrafConfigService` and remove URM interactions. +- Use the updated HTTP client for the authorization service. +- Make `tagKeys` and `tagValues` work for edge cases involving fields. +- Correctly parse float as 64-bits. +- Add simple metrics related to installed templates. +- Remove extra multiplication of retention policies in onboarding. +- Use the `fluxinit` package to initialize the Flux library instead of builtin. +- Add Logger to the constructor function to ensure the log field is initialized. +- Return an empty iterator instead of null in `tagValues`. +- Fix the `/ready` response content type to return `application/json`. + +## v2.0.0-rc.3 [2020-10-29] + +### Features + +- Upgrade to [Flux v0.91.0](/{{< latest "flux" >}}/release-notes/#v0910-2020-10-26). +- Enable window aggregate mean pushdown. +- Add `newMultiShardArrayCursors` to aggregate array cursors. +- UI updates: + - Upgrade `papaparse` to 5.2.0. + - Upgrade `flux-lsp-browser` to v0.5.21. + - Add properties for storing your tick generation selections, including a `generateAxisTicks` property to turn this feature on and off. + - Update generate ticks into an array of properties for each axis. + - Add the `legendColorizeRows` property to toggle the color on and off in the legend. + +### Bug Fixes + +- Resolve `invalid operation: fs.Bavail` error that occurred in some cases using when `DiskUsage()`. Now, `fs.Bavail` is always converted to `unit64` to ensure the types in an expression align. +- Refactor notifications to isolate the `notification/endpoint/service` package and move the rule service into its own package. +- Update to clear log out. +- Refactor to allow `newIndexSeriesCursor()` to accept an `influxql.Expr`. +- Remove unreferenced packages. + +## v2.0.0-rc.2 [2020-10-22] + +### Features + +- Upgrade to [Flux v0.90.0](/{{< latest "flux" >}}/release-notes/#v0900-2020-10-19). +- Add `--force` option to the `influx stacks rm` command, which lets you remove a stack without the confirmation prompt. +- Add `aggregate_resultset` for mean aggregate pushdown to optimize windowed results. +- Return an error if adding a resource to a stack (`influx stacks update --addResource`) fails due to an invalid resource type or resource ID. + +### Bug Fixes + +- Update `pkger` test templates to use valid Flux to avoid `found unexpected argument end` error. Previously, any template with a `v.dashboardVariable` returned an `undefined identifier v` error. +- Update the InfluxDB configuration file `/etc/influxdb/influxdb.conf` to recognize the user's home directory. Previously, if a user (other than root user) ran the `upgrade` command, a permissions error occurred. +- Remove the Telegraf RAS Daemon plugin and other miscellaneous Telegraf plugin updates. +- Update the `derivative` in the InfluxDB UI (`ui/src/timeMachiner`) to specify the `unit` is one second (`1s`). +- Enable the new `AuthorizationService` from authorization package in the `launcher` package (`cmd\influxd\launcher`). +- Update `config upgrade` to save the correct InfluxDB configuration filename. + +## v2.0.0-rc.1 [2020-10-14] + +### Features +- Add [`influx upgrade`](/influxdb/v2.1/reference/cli/influxd/upgrade/) command for upgrading from 1.x to 2.0. +- Upgrade to Flux v0.89.0. + +### Bug Fixes +- Enable scrapers. (Scrapers did not work in rc0.) +- Update default number of tasks listed with `influx task list` to 100. +- Add support for [duration unit identifiers](/{{< latest "flux" >}}/spec/lexical-elements/#duration-literals) to templates. +- Preserve cell colors in imported and exported templates. +- Resolve issue to ensure the `influx` CLI successfully returns a single Telegraf configuration. +- Ensure passwords are at least 8 characters in `influx setup`. + +## v2.0.0-rc.0 [2020-09-29] + +{{% warn %}} +#### Manual upgrade required + +To simplify the migration for existing users of InfluxDB 1.x, this release includes significant breaking changes that require a manual upgrade from all alpha and beta versions. For more information, see [Upgrade to InfluxDB OSS 2.0rc](/influxdb/v2.1/reference/upgrading/rc-upgrade-guide/), +{{% /warn %}} + +### Breaking changes + +#### Manual upgrade + +- To continue using data from InfluxDB 2.0 beta 16 or earlier, you must move all existing data out of the `~/.influxdbv2` (or equivalent) path, including `influxd.bolt`. All existing dashboards, tasks, integrations, alerts, users, and tokens must be recreated. For information on how to migrate your data, see [Upgrade to InfluxDB OSS 2.0rc](/influxdb/v2.1/reference/upgrading/rc-upgrade-guide/). + +#### Port update to 8086 + +- Change the default port of InfluxDB from 9999 back to 8086. If you would still like to run on port 9999, you can start `influxd` with the `--http-bind-address` option. You must also [update any InfluxDB CLI configuration profiles](/influxdb/v2.1/reference/cli/influx/config/set/) with the new port number. + +#### Support for 1.x storage engine and InfluxDB 1.x compatibility API + +- Port the TSM1 storage engine. This change supports a multi-shared storage engine and InfluxQL writes and queries using the InfluxDB 1.x API compatibility [`/write`](/influxdb/v2.1/reference/api/influxdb-1x/write/) and [`/query`](/influxdb/v2.1/reference/api/influxdb-1x/query/) endpoints. + +#### Disable delete with predicate API + +- Disable the delete with predicate API (`/api/v2/delete`). This API now returns a `501 Not implemented` message. + +### Features + +#### Load Data redesign + +- Update the Load Data page to increase discovery and ease of use. Now, you can [load data from sources in the InfluxDB user interface](/influxdb/v2.1/write-data/no-code/load-data/). + +#### Community templates added to InfluxDB UI + +- Add [InfluxDB community templates](/influxdb/v2.1/influxdb-templates/) directly in the InfluxDB user interface (UI). + +#### New data sources + +- Add InfluxDB v2 Listener, NSD, OPC-UA, and Windows Event Log to the Sources page. + +#### CLI updates + +- Add option to print raw query results in [`influx query`](/influxdb/v2.1/reference/cli/influx/query/). +- Add ability to export resources by name using [`influx export`](/influxdb/v2.1/reference/cli/influx/export/). +- Add new processing options and enhancements to [`influx write`](/influxdb/v2.1/reference/cli/influx/write/). +- Add `--active-config` flag to [`influx` commands](/influxdb/v2.1/reference/cli/influx/#commands) to set the configuration for a single command. +- Add `influxd`[configuration options](/influxdb/v2.1/reference/config-options/#configuration-options) for storage options and InfluxQL coordinator tuning. +- Add `max-line-length` switch to the [`influx write`](/influxdb/v2.1/reference/cli/influx/write/) command to address `token too long errors` for large inputs. + +#### API updates + +- List buckets in the API now supports the `after` (ID) parameter as an alternative to `offset`. + +#### Task updates + +- Record last success and failure run times in the task. +- Inject the task option `latestSuccessTime` in Flux `Extern`. + +### Bug Fixes + +- Add description to [`influx auth`](/influxdb/v2.1/reference/cli/influx/auth/) command outputs. +- Resolve issues with check triggers in notification tasks by including the edge of the observed boundary. +- Detect and provide warning about duplicate tag names when writing CSV data using `influx write`. +- Ensure the group annotation does not override the existing line part (measurement, field, tag, time) in a CSV group annotation. +- Added `PATCH` to the list of allowed methods. + +## v2.0.0-beta.16 [2020-08-06] + +{{% warn %}} +This release includes breaking changes: +- Remove `influx repl` command. To use the Flux REPL, build the REPL from source. +- Drop deprecated `/packages` route tree. +- Support more types for template `envRef` default value and require explicit default values. +- Remove orgs/labels nested routes from the API. +{{% /warn %}} + +### Features + +- Add resource links to a stack's resources from public HTTP API list/read calls. +- Enhance resource creation experience when limits are reached. +- Add `dashboards` command to `influx` CLI. +- Allow user onboarding to optionally set passwords. +- Limit query response sizes for queries built in QueryBuilder by requiring an aggregate window. + +### Bug Fixes + +- Require all `influx` CLI flag arguments to be valid. +- Dashboard cells correctly map results when multiple queries exist. +- Dashboard cells and overlay use UTC as query time when toggling to UTC timezone. +- Bucket names may not include quotation marks. + +### UI Improvements + +- Alerts page filter inputs now have tab indices for keyboard navigation. + +## v2.0.0-beta.15 [2020-07-23] + +### Features + +- Add event source to stacks. +- Add ability to uninstall stacks. +- Drop deprecated `influx pkg` commands. +- Add Telegraf management commands to `influx` CLI. +- Enable dynamic destination for the `influx` CLI configuration file. + +### Bug Fixes + +- Allow 0 to be the custom set minimum value for y domain. +- Single Stat cells render properly in Safari. +- Limit variable querying when submitting queries to used variables. + +## v2.0.0-beta.14 [2020-07-08] + +### Features + +- Extend `influx stacks update` command with ability to add resources without apply template. +- Consolidate all InfluxDB template and stack functionality into two new public APIs: `/api/v2/templates` and `/api/v2/stacks`. +- Extend template `Summary` and `Diff` nested types with `kind` identifiers. +- Add static builds for Linux. +- Update Flux to v.0.71.1. + +### Bug Fixes + +- Don't overwrite build date set via `ldflags`. +- Fix issue where define query was unusable after importing a Check. +- Update documentation links + +## v2.0.0-beta.13 [2020-06-25] + +### Features + +- Cancel submitted queries in the Data Explorer. +- Extend templates with the source `file|url|reader`. +- Collect stats on installed InfluxData community template usage. +- Allow raw `github.com` host URLs for `yaml|json|jsonnet` URLs in InfluxDB templates. +- Allow for remote files for all `influx template` commands. +- Extend stacks API with update capability. +- Add support for config files to `influxd` and any `cli.NewCommand` use case. +- Extend `influx stacks` command with new `influx stacks update` command. +- Skip resources in a template by kind or by `metadata.name`. +- Extend `influx apply` with resource filter capabilities. +- Provide active configuration when running `influx config` without arguments. +- Enable `influxd` binary to look for a configuration file on startup. +- Add environmental default values to the template parser. +- Templates will store which dashboard variable should be selected by default. + +### Bug Fixes + +- Fix `uint` overflow during setup on 32bit systems. +- Drop support for `--local` flag within `influx` CLI. +- Fix issue where undefined queries in cells result in error in dashboard. +- Add support for day and week time identifiers in the CLI for bucket and setup commands. +- Cache dashboard cell query results to use as a reference for cell configurations. +- Validate `host-url` for `influx config create` and `influx config set` commands. +- Fix `influx` CLI flags to accurately depict flags for all commands. + +## v2.0.0-beta.12 [2020-06-12] + +### Features + +- Add option for Cloud users to use the `influx` CLI to interact with a Cloud instance. For more information, see how to [download and install the influx CLI](/influxdb/v2.1/get-started/) and then learn more about how the [influx - InfluxDB command line interface](/influxdb/v2.1/reference/cli/influx/) works. +- Consolidate `influx apply` commands under templates. Remove some nesting of the `influx` CLI commands. +- Make all `influx apply` applications stateful through stacks. +- Add ability to export a stack's existing resource state using `influx export`. +- Update `influx apply` commands with improved usage and examples in long form. +- Update `influx` CLI to include the `-version` command and return the User-Agent header. +- Add `RedirectTo` functionality to ensure Cloud users are redirected to the page that they were trying access after logging into Cloud. +- Maintain sort order on a dashboard after navigating away. +- Allow tasks to open in new tabs. + +### Bug Fixes + +- Support organization name and ID in DBRP operations. +- Prevent the CLI from failing when an unexpected flag is entered in the CLI. +- `influx delete` now respects the configuration settings. +- Store initialization for `pkger` enforced on reads. +- Backfill missing `fillColumns` field for histograms in `pkger`. +- Notify the user how to escape presentation mode when the feature is toggled. + +### UI Improvements + +- Display bucket ID in bucket list and enable 1-click copying. +- Update Tokens list to be consistent with other resource lists. +- Reduce the number of variables being hydrated when toggling variables. +- Redesign dashboard cell loading indicator to be more obvious. + +## v2.0.0-beta.11 [2020-05-27] + +{{% warn %}} +The beta 11 version was **not released**. Changes below are included in the beta 12 release. +{{% /warn %}} + +### Features + +- Ability to set UTC time for a custom time range query. +- Ability to set a minimum or maximum value for the y-axis visualization setting (rather than requiring both). +- New `csv2lp` library for converting CSV (comma separated values) to InfluxDB line protocol. +- Add influxdb version to the InfluxDB v2 API `/health` endpoint. + +### Bug Fixes + +- Automatically adjust the drop-down list width to ensure the longest item in a list is visible. +- Fix bug in Graph + Single Stat visualizations to ensure `timeFormat` persists. +- Authorizer now exposes the full permission set. This adds the ability to derive which organizations the Authorizer has access to read or write to without using a User Request Management (URM) service. +- Fix issue causing variable selections to hydrate all variable values, decreasing the impact on network requests. +- Resolve scrollbar issues to ensure datasets are visible and scrollable. +- Check status now displays a warning if loading a large amount. + +## v2.0.0-beta.10 [2020-05-07] + +### Features + +- Add ability to delete a stack and all associated resources. +- Enforce DNS name compliance on the `metadata.name` field in all `pkger` resources. +- Add stateful `pkg` management with stacks. + +### Bug Fixes + +- Ensure `UpdateUser` cleans up the index when updating names. +- Ensure Checks can be set for zero values. + +### UI Improvements + +- Create buckets in the Data Explorer and Cell Editor. + +--- + +## v2.0.0-beta.9 [2020-04-23] + +### Bug Fixes +- Add index for URM by user ID to improve lookup performance. +- Existing session expiration time is respected on session renewal. +- Make CLI respect environment variables and flags and extend support for config orgs to all commands. + +### UI Improvements +- Update layout of alerts page to work on all screen sizes. +- Sort dashboards on Getting Started page by recently modified. +- Add single-color schemes for visualizations: Solid Red, Solid Blue, Solid Yellow, Solid Green, and Solid Purple. + +--- + +## v2.0.0-beta.8 [2020-04-10] + +### Features +- Add `influx config` CLI command to switch back to previous activated configuration. +- Introduce new navigation menu. +- Add `-file` option to `influx query` and `influx task` CLI commands. +- Add support for command line options to limit memory for queries. + +### Bug Fixes +- Fix card size and layout issues in dashboards index view. +- Fix check graph font and lines defaulting to black causing graph to be unreadable +- Fix text-wrapping display issue and popover sizing bug when adding labels to a resource. +- Respect the now-time of the compiled query if provided. +- Fix spacing between ticks. +- Fix typos in Flux functions list. + +### UI Improvements +- Update layout of Alerts page to work on all screen sizes. +- Sort dashboards on Getting Started page by recently modified. + +--- + +## v2.0.0-beta.7 [2020-03-27] + +### Features + +- Add option to display dashboards in [light mode](/influxdb/v2.1/visualize-data/dashboards/control-dashboard/#toggle-dark-mode-and-light-mode). +- Add [shell `completion` commands](/influxdb/v2.1/reference/cli/influx/completion/) to the `influx` CLI. + specified shell (`bash` or `zsh`). +- Make all `pkg` resources unique by `metadata.name` field. +- Ensure Telegraf configuration tokens aren't retrievable after creation. New tokens can be created after Telegraf has been setup. +- [Delete bucket by name](/influxdb/v2.1/organizations/buckets/delete-bucket/#delete-a-bucket-by-name) using the `influx` CLI. +- Add helper module to write line protocol to specified url, org, and bucket. +- Add [`pkg stack`](/influxdb/v2.1/reference/cli/influx/stacks) for stateful package management. +- Add `--no-tasks` flag to `influxd` to disable scheduling of tasks. +- Add ability to output CLI output as JSON and hide table headers. +- Add an [easy way to switch configurations](/influxdb/v2.1/reference/cli/influx/config/#quickly-switch-between-configurations) using the `influx` CLI. + +### Bug fixes + +- Fix NodeJS logo display in Firefox. +- Fix Telegraf configuration bugs where system buckets were appearing in the Buckets list. +- Fix threshold check bug where checks could not be created when a field had a space in the name. +- Reuse slices built by iterator to reduce allocations. +- Updated duplicate check error message to be more explicit and actionable. + +### UI improvements + +- Redesign OSS Login page. +- Display graphic when a dashboard has no cells. + +--- + +## v2.0.0-beta.6 [2020-03-12] + +### Features +- Clicking on bucket name takes user to Data Explorer with bucket selected. +- Extend pkger (InfluxDB Templates) dashboards with table view support. +- Allow for retention to be provided to `influx setup` command as a duration. +- Extend `influx pkg export all` capabilities to support filtering by lable name and resource type. +- Added new login and sign-up screen for InfluxDB Cloud users that allows direct login from their region. +- Added new `influx config` CLI for managing multiple configurations. + +### Bug Fixes +- Fixed issue where tasks were exported for notification rules. +- Fixed issue where tasks were not exported when exporting by organization ID. +- Fixed issue where tasks with imports in the query would break in pkger. +- Fixed issue where selecting an aggregate function in the script editor did not + add the function to a new line. +- Fixed issue where creating a dashboard variable of type "map" piped the incorrect + value when map variables were used in queries. +- Added missing usernames to `influx auth` CLI commands. +- Disabled group functionality for check query builder. +- Fixed cell configuration error that popped up when users created a dashboard + and accessed the "Disk Usage" cell for the first time. +- Listing all the default variables in the Variable tab of the script editor. +- Fixed bug that prevented the interval status on the dashboard header from + refreshing on selections. +- Updated table custom decimal feature for tables to update on focus. +- Fixed UI bug that set Telegraf config buttons off-center and resized config + selections when filtering through the data. +- Fixed UI bug that caused dashboard cells to error when using `v.bucket` for the first time. +- Fixed appearance of client library logos in Safari. +- Fixed UI bug that prevented checks created with the query builder from updating. +- Fixed a bug that prevented dashboard cell queries from working properly when + creating group queries using the query builder. + +### UI Improvements +- Swap `billingURL` with `checkoutURL`. +- Move Cloud navigation to top of page instead of within left side navigation. +- Adjust aggregate window periods to use duration input with validation. + +--- + +## v2.0.0-beta.5 [2020-02-27] + +### Features +- Update Flux to v0.61.0. +- Add secure flag to session cookie. +- Add optional secret value flag to `influx secret` command. + +### Bug Fixes +- Sort dashboards on homepage alphabetically. +- Tokens page now sorts by status. +- Set the default value of tags in a check. +- Fix sort by variable type. +- Calculate correct stacked line cumulative when lines are different lengths. +- Resource cards are scrollable. +- Query Builder groups on column values, not tag values. +- Scatterplots render tooltips correctly. +- Remove pkger gauge chart requirement for color threshold type. +- Remove secret confirmation from `influx secret update`. + +--- + +## v2.0.0-beta.4 [2020-02-14] + +### Features +- Added labels to buckets. +- Connect Monaco Editor to Flux LSP server. +- Update Flux to v0.59.6. + +### Bug Fixes +- Revert bad indexing of `UserResourceMappings` and `Authorizations`. +- Prevent gauge visualization from becoming too small. + +--- + +## v2.0.0-beta.3 [2020-02-11] + +### Features +- Extend `influx cli pkg command` with ability to take multiple files and directories. +- Extend `influx cli pkg command` with ability to take multiple URLs, files, + directories, and stdin at the same time. +- `influx` CLI can manage secrets. + +### Bug Fixes +- Fix notification rule renaming panics in UI. +- Fix the tooltip for stacked line graphs. +- Fixed false success notification for read-only users creating dashboards. +- Fix issue with pkger/http stack crashing on duplicate content type. + +--- + +## v2.0.0-beta.2 [2020-01-24] + +### Features +- Change Influx packages to be CRD compliant. +- Allow trailing newline in credentials file and CLI integration. +- Add support for prefixed cursor search to ForwardCursor types. +- Add backup and restore. +- Introduce resource logger to tasks, buckets and organizations. + +### Bug Fixes +- Check engine closed before collecting index metrics. +- Reject writes which use any of the reserved tag keys. + +### UI Improvements +- Swap `billingURL` with `checkoutURL`. +- Move Cloud navigation to top of page instead of within left side navigation. +- Adjust aggregate window periods to use duration input with validation. + +--- + +## v2.0.0-beta.1 [2020-01-08] + +### Features +- Add support for notification endpoints to `influx` templates and packages. +- Drop `id` prefix for secret key requirement for notification endpoints. +- Add support for check resource to `pkger` parser. +- Add support for check resource `pkger` dry run functionality +- Add support for check resource `pkger` apply functionality +- Add support for check resource `pkger` export functionality +- Add new `kv.ForwardCursor` interface. +- Add support for notification rule to `pkger` parser. +- Add support for notification rule `pkger` dry run functionality +- Add support for notification rule `pkger` apply functionality. +- Add support for notification rule `pkger` export functionality. +- Add support for tasks to `pkger` parser. +- Add support for tasks to `pkger` dry run functionality +- Add support for tasks to `pkger` apply functionality. +- Add support for tasks to `pkger` export functionality. +- Add `group()` to Query Builder. +- Add last run status to check and notification rules. +- Add last run status to tasks. +- Extend `pkger` apply functionality with ability to provide secrets outside of package. +- Add hide headers flag to `influx` CLI task find command. +- Manual overrides for readiness endpoint. +- Drop legacy inmem service implementation in favor of KV service with inmem dependency. +- Drop legacy bolt service implementation in favor of KV service with bolt dependency. +- While creating check, also display notification rules that would match check based on tag rules. +- Increase default bucket retention period to 30 days. +- Add toggle to table thresholds to allow users to choose between setting threshold colors to text or background. +- Add developer documentation. +- Capture User-Agent header as query source for logging purposes. + +### Bug Fixes +- Ensure environment variables are applied consistently across command and fixes issue where `INFLUX_` environment variable prefix was not set globally. +- Remove default frontend sorting when flux queries specify sorting. +- Store canceled task runs in the correct bucket. +- Update `sortby` functionality for table frontend sorts to sort numbers correctly. +- Prevent potential infinite loop when finding tasks by organization. +- Retain user input when parsing invalid JSON during import. +- Fix test issues due to multiple flush/sign-ins being called in the same test suite. +- Update `influx` CLI to show only "see help" message, instead of the whole usage. +- Fix notification tag-matching rules and enable tests to verify. +- Extend y-axis when stacked graph is selected. +- Fix query reset bug that was resetting query in script editor whenever dates were changed. +- Fix table threshold bug defaulting set colors to the background. +- Time labels no longer squished to the left. +- Fix underlying issue with disappearing queries made in Advanced Mode. +- Prevent negative zero and allow zero to have decimal places. +- Limit data loader bucket selection to non system buckets. + +### UI Improvements +- Add honeybadger reporting to create checks. + +--- + +## v2.0.0-alpha.21 [2019-12-13] + +### Features +- Add stacked line layer option to graphs. +- Annotate log messages with trace ID, if available. +- Bucket create to accept an organization name flag. +- Add trace ID response header to query endpoint. + +### Bug Fixes +- Allow table columns to be draggable in table settings. +- Light up the home page icon when active. +- Make numeric inputs first class citizens. +- Prompt users to make a dashboard when dashboards are empty. +- Remove name editing from query definition during threshold check creation. +- Wait until user stops dragging and releases marker before zooming in after threshold changes. +- Adds properties to each cell on `GET /dashboards/{dashboardID}`. +- Gracefully handle invalid user-supplied JSON. +- Fix crash when loading queries built using the query builder. +- Create cell view properties on dashboard creation. +- Update scrollbar style. +- Fixed table UI threshold colorization issue. +- Fixed windowPeriod issue that stemmed from Webpack rules. +- Added delete functionality to note cells so that they can be deleted +- Fix failure to create labels when creating Telegraf configs +- Fix crash when editing a Telegraf config. +- Updated start/end time functionality so that custom script time ranges overwrite dropdown selections. + +--- + +## v2.0.0-alpha.20 [2019-11-20] + +### Features +- Add TLS insecure skip verify to influx CLI. +- Extend influx cli user create to allow for organization ID and user passwords to be set on user. +- Auto-populate organization IDs in the code samples. +- Expose bundle analysis tools for front end resources. +- Allow users to view just the output section of a Telegraf config. +- Allow users to see string data in single stat graph type. + +### Bug Fixes +- Fix long startup when running `influx help`. +- Mock missing Flux dependencies when creating tasks. +- Ensure array cursor iterator stats accumulate all cursor stats. +- Hide Members section in Cloud environments. +- Change how cloud mode is enabled. +- Merge front end development environments. +- Refactor table state logic on the front end. +- Arrows in tables show data in ascending and descending order. +- Sort by retention rules now sorts by second. +- Horizontal scrollbar no longer covering data; +- Allow table columns to be draggable in table settings. +- Light up the home page icon when active. +- Make numeric inputs first-class citizens. +- Prompt users to make a dashboard when dashboards are empty. +- Remove name editing from query definition during threshold check creation. +- Wait until user stops dragging and releases marker before zooming in after threshold changes. + +### UI Improvements +- Redesign cards and animations on Getting Started page. +- Allow users to filter with labels in Telegraf input search. + +--- + +## v2.0.0-alpha.19 [2019-10-30] + +### Features +- Add shortcut for toggling comments and submitting in Script Editor. + +### UI Improvements +- Redesign page headers to be more space-efficient. +- Add 403 handler that redirects back to the sign-in page on oats-generated routes. + +### Bug Fixes +- Ensure users are created with an active status. +- Added missing string values for `CacheStatus` type. +- Disable saving for threshold check if no threshold selected. +- Query variable selector shows variable keys, not values. +- Create Label overlay disables the submit button and returns a UI error if name field is empty. +- Log error as info message on unauthorized API call attempts. +- Ensure `members` and `owners` endpoints lead to 404 when organization resource does not exist. +- Telegraf UI filter functionality shows results based on input name. +- Fix Telegraf UI sort functionality. +- Fix task UI sort functionality. +- Exiting a configuration of a dashboard cell properly renders the cell content. +- Newly created checks appear on the checklist. +- Changed task runs success status code from 200 to 201 to match Swagger documentation. +- Text areas have the correct height. + +--- + +## v2.0.0-alpha.18 [2019-09-26] + +### Features +- Add jsonweb package for future JWT support. +- Added the JMeter Template dashboard. + +### UI Improvements +- Display dashboards index as a grid. +- Add viewport scaling to html meta for responsive mobile scaling. +- Remove rename and delete functionality from system buckets. +- Prevent new buckets from being named with the reserved `_` prefix. +- Prevent user from selecting system buckets when creating Scrapers, Telegraf configurations, read/write tokens, and when saving as a task. +- Limit values from draggable threshold handles to 2 decimal places. +- Redesign check builder UI to fill the screen and make more room for composing message templates. +- Move Tokens tab from Settings to Load Data page. +- Expose all Settings tabs in navigation menu. +- Added Stream and table functions to query builder. + +### Bug Fixes +- Remove scrollbars blocking onboarding UI step. + +--- + +## v2.0.0-alpha.17 [2019-08-14] + +### Features +- Optional gzip compression of the query CSV response. +- Add task types. +- When getting task runs from the API, runs will be returned in order of most recently scheduled first. + +### Bug Fixes +- Fix authentication when updating a task with invalid org or bucket. +- Update the documentation link for Telegraf. +- Fix to surface errors properly as task notifications on create. +- Fix limiting of get runs for task. + +--- + +## v2.0.0-alpha.16 [2019-07-25] + +### Bug Fixes +- Add link to documentation text in line protocol upload overlay. +- Fix issue in Authorization API, can't create auth for another user. +- Fix Influx CLI ignored user flag for auth creation. +- Fix the map example in the documentation. +- Ignore null/empty Flux rows which prevents a single stat/gauge crash. +- Fixes an issue where clicking on a dashboard name caused an incorrect redirect. +- Upgrade templates lib to 0.5.0. +- Upgrade giraffe lib to 0.16.1. +- Fix incorrect notification type for manually running a task. +- Fix an issue where canceled tasks did not resume. + +--- + +## v2.0.0-alpha.15 [2019-07-11] + +### Features +- Add time zone support to UI. +- Added new storage inspection tool to verify TSM files. + +### Bug Fixes +- Fix incorrect reporting of tasks as successful when errors occur during result iteration. + +#### Known Issues +The version of Flux included in Alpha 14 introduced `null` support. +Most issues related to the `null` implementation have been fixed, but one known issue remains – +The `map()` function panics if the first record processed has a `null` value. + +--- + +## v2.0.0-alpha.14 [2019-06-28] + +### Features +- Add `influxd inspect verify-wal` tool. +- Move to [Flux 0.34.2](/{{< latest "flux" >}}/release-notes/#v0342-2019-06-27) - + includes new string functions and initial multi-datasource support with `sql.from()`. +- Only click save once to save cell. +- Enable selecting more columns for line visualizations. + +### UI Improvements +- Draw gauges correctly on HiDPI displays. +- Clamp gauge position to gauge domain. +- Improve display of error messages. +- Remove rendering bottleneck when streaming Flux responses. +- Prevent variable dropdown from clipping. + +--- + +## v2.0.0-alpha.13 [2019-06-13] + +### Features +- Add static templates for system, Docker, Redis, Kubernetes. + +--- + +## v2.0.0-alpha.12 [2019-06-13] + +### Features +- Enable formatting line graph y ticks with binary prefix. +- Add x and y column pickers to graph types. +- Add option to shade area below line graphs. + +### Bug Fixes +- Fix performance regression in graph tooltips. + +--- + +## v2.0.0-alpha.11 [2019-05-31] + +### Bug Fixes +- Correctly check if columnKeys include xColumn in heatmap. + +--- + +## v2.0.0-alpha.10 [2019-05-30] + +### Features +- Add heatmap visualization type. +- Add scatterplot graph visualization type. +- Add description field to tasks. +- Add CLI arguments for configuring session length and renewal. +- Add smooth interpolation option to line graphs. + +### Bug Fixes +- Removed hardcoded bucket for Getting Started with Flux dashboard. +- Ensure map type variables allow for selecting values. +- Generate more idiomatic Flux in query builder. +- Expand tab key presses to two spaces in the Flux editor. +- Prevent dragging of variable dropdowns when dragging a scrollbar inside the dropdown. +- Improve single stat computation. +- Fix crash when opening histogram settings with no data. + +### UI Improvements +- Render checkboxes in query builder tag selection lists. +- Fix jumbled card text in Telegraf configuration wizard. +- Change scrapers in scrapers list to be resource cards. +- Export and download resource with formatted resource name with no spaces. + +--- + +## v2.0.0-alpha.9 [2019-05-01] + +{{% warn %}} +**This will remove all tasks from your InfluxDB v2.0 instance.** + +Before upgrading, [export all existing tasks](/influxdb/v2.1/process-data/manage-tasks/export-task/). After upgrading, [reimport your exported tasks](/influxdb/v2.1/process-data/manage-tasks/create-task/#import-a-task). +{{% /warn %}} + +### Features +- Set autorefresh of dashboard to pause if absolute time range is selected. +- Switch task back end to a more modular and flexible system. +- Add org profile tab with ability to edit organization name. +- Add org name to dashboard page title. +- Add cautioning to bucket renaming. +- Add option to generate all access token in tokens tab. +- Add option to generate read/write token in tokens tab. +- Add new Local Metrics Dashboard template that is created during Quick Start. + +### Bug Fixes +- Fixed scroll clipping found in label editing flow. +- Prevent overlapping text and dot in time range dropdown. +- Updated link in notes cell to a more useful site. +- Show error message when adding line protocol. +- Update UI Flux function documentation. +- Update System template to support math with floats. +- Fix the `window` function documentation. +- Fix typo in the `range` Flux function example. +- Update the `systemTime` function to use `system.time`. + +### UI Improvements +- Add general polish and empty states to Create Dashboard from Template overlay. + +--- + +## v2.0.0-alpha.8 [2019-04-12] + +### Features +- Add the ability to edit token's description. +- Add the option to create a dashboard from a template. +- Add the ability to add labels on variables. +- Add switch organizations dropdown to home navigation menu item. +- Add create org to side nav. +- Add "Getting Started with Flux" template. +- Update to Flux v0.25.0. + +### Bug Fixes +- Update shift to timeShift in Flux functions sidebar. + +### UI Improvements +- Update cursor to grab when hovering draggable areas. +- Sync note editor text and preview scrolling. +- Add the ability to create a bucket when creating an organization. + +--- + +## v2.0.0-alpha.7 [2019-03-28] + +### Features +- Insert Flux function near cursor in Flux Editor. +- Enable the use of variables in the Data Explorer and Cell Editor Overlay. +- Add a variable control bar to dashboards to select values for variables. +- Add ability to add variable to script from the side menu. +- Use time range for meta queries in Data Explorer and Cell Editor Overlay. +- Fix screen tearing bug in raw data view. +- Add copy to clipboard button to export overlays. +- Enable copying error messages to the clipboard from dashboard cells. +- Add the ability to update token's status in token list. +- Allow variables to be re-ordered within control bar on a dashboard. +- Add the ability to delete a template. +- Save user preference for variable control bar visibility and default to visible. +- Add the ability to clone a template. +- Add the ability to import a variable. + +### Bug Fixes +- Fix mismatch in bucket row and header. +- Allows user to edit note on cell. +- Fix empty state styles in scrapers in org view. +- Fix bucket creation error when changing retention rules types. +- Fix task creation error when switching schedule types. +- Fix hidden horizontal scrollbars in flux raw data view. +- Fix screen tearing bug in raw data View. +- Fix routing loop. + +### UI Improvements +- Move bucket selection in the query builder to the first card in the list. +- Ensure editor is automatically focused in Note Editor. +- Add ability to edit a template's name. + +--- + +## v2.0.0-alpha.6 [2019-03-15] + +### Release Notes + +{{% warn %}} +We have updated the way we do predefined dashboards to [include Templates](https://github.com/influxdata/influxdb/pull/12532) +in this release which will cause existing Organizations to not have a System +dashboard created when they build a new Telegraf configuration. +In order to get this functionality, remove your existing data and start from scratch. + +_**This will remove all data from your InfluxDB v2.0 instance including time series data.**_ + +###### Linux and macOS +```sh +rm ~/.influxdbv2/influxd.bolt +``` + +Once completed, `v2.0.0-alpha.6` can be started. +{{% /warn %}} + +### Features +- Add ability to import a dashboard. +- Add ability to import a dashboard from organization view. +- Add ability to export a dashboard and a task. +- Add `run` subcommand to `influxd` binary. This is also the default when no subcommand is specified. +- Add ability to save a query as a variable from the Data Explorer. +- Add System template on onboarding. + +### Bug Fixes +- Stop scrollbars from covering text in Flux editor. + +### UI Improvements +- Fine tune keyboard interactions for managing labels from a resource card. + +--- + +## v2.0.0-alpha.5 [2019-03-08] + +{{% warn %}} +This release includes a breaking change to the format in which Time-Structured Merge Tree (TSM) and index data are stored on disk. +_**Existing local data will not be queryable after upgrading to this release.**_ + +Prior to installing this release, remove all storage-engine data from your local InfluxDB 2.x installation. +To remove only TSM and index data and preserve all other other InfluxDB 2.x data (organizations, buckets, settings, etc), +run the following command. + +###### Linux and macOS +```sh +rm -r ~/.influxdbv2/engine +``` + +Once completed, InfluxDB v2.0.0-alpha.5 can be started. +{{% /warn %}} + +### Features +- Add labels to cloned tasks. +- Add ability to filter resources by clicking a label. +- Add ability to add a member to org. +- Improve representation of TSM tagsets on disk. +- Add ability to remove a member from org. +- Update to Flux v0.21.4. + +### Bug Fixes +- Prevent clipping of code snippets in Firefox. +- Prevent clipping of cell edit menus in dashboards. + +### UI Improvements +- Make code snippet copy functionality easier to use. +- Always show live preview in note cell editor. +- Redesign scraper creation workflow. +- Show warning in Telegraf and scraper lists when user has no buckets. +- Streamline label addition, removal, and creation from the dashboards list. + +--- + +## v2.0.0-alpha.4 [2019-02-21] + +### Features +- Add the ability to run a task manually from tasks page. +- Add the ability to select a custom time range in explorer and dashboard. +- Display the version information on the login page. +- Add the ability to update a variable's name and query. +- Add labels to cloned dashboard. +- Add ability filter resources by label name. +- Add ability to create or add labels to a resource from labels editor. +- Update to Flux v0.20. + +### Bug Fixes +- Update the bucket retention policy to update the time in seconds. + +### UI Improvements +- Update the preview in the label overlays to be shorter. +- Add notifications to scrapers page for created/deleted/updated scrapers. +- Add notifications to buckets page for created/deleted/updated buckets. +- Update the admin page to display error for password length. + +--- + +## v2.0.0-alpha.3 [2019-02-15] + +### Features +- Add the ability to name a scraper target. +- Display scraper name as the first and only updatable column in scrapers list. +- Add the ability to view runs for a task. +- Display last completed run for tasks list. +- Add the ability to view the logs for a specific task run. + +### Bug Fixes +- Update the inline edit for resource names to guard for empty strings. +- Prevent a new template dashboard from being created on every Telegraf config update. +- Fix overlapping buttons in Telegraf verify data step. + +### UI Improvements +- Move the download Telegraf config button to view config overlay. +- Combine permissions for user by type. + +--- + +## v2.0.0-alpha.2 [2019-02-07] + +### Features +- Add instructions button to view `$INFLUX_TOKEN` setup for Telegraf configs. +- Save the `$INFLUX_TOKEN` environmental variable in Telegraf configs. +- Update Tasks tab on Organizations page to look like Tasks Page. +- Add view button to view the Telegraf config toml. +- Add plugin information step to allow for config naming and configure one plugin at a time. +- Update Dashboards tab on Organizations page to look like Dashboards Page. + +### Bug Fixes +- Update the System Telegraf Plugin bundle to include the Swap plugin. +- Revert behavior allowing users to create authorizations on behalf of another user. + +### UI Improvements +- Change the wording for the plugin config form button to "Done." +- Change the wording for the Collectors configure step button to "Create and Verify." +- Standardize page loading spinner styles. +- Show checkbox on "Save As" button in data explorer. +- Make collectors plugins side bar visible in only the configure step. +- Swap retention policies on Create bucket page. + +--- + +## v2.0.0-alpha.1 [2019-01-23] + +This is the initial alpha release of InfluxDB 2.0. diff --git a/content/influxdb/v2.1/reference/release-notes/supported-release.md b/content/influxdb/v2.1/reference/release-notes/supported-release.md new file mode 100644 index 0000000000..c3afc30bc5 --- /dev/null +++ b/content/influxdb/v2.1/reference/release-notes/supported-release.md @@ -0,0 +1,36 @@ +--- +title: Supported releases +description: > + Supported releases made to InfluxData. +menu: + influxdb_2_1_ref: + name: Supported releases + parent: Release notes +weight: 204 +related: + - /influxdb/v2.1/reference/release-notes +--- + +InfluxData provides support for the following minor, major, and maintenance releases: + +##### Major + +- Includes new features, enhancements to existing features, and applicable error corrections from all prior releases. +- InfluxDB supports backward compatibility within a major release. + +##### Minor (x.Y.z) + +- Includes new minor features, enhancements to existing features, and includes applicable error corrections from prior minor and maintenance releases. + +##### Maintenance (x.y.Z) + +- Includes error corrections severely affecting a number of customers that cannot wait for the next major or minor release. Include applicable error corrections made in prior maintenance releases. Released as as needed based on customer feedback and outstanding errors (no predefined schedule). +- Interim (x.y.z.A) Fourth digit (or beyond) are an exception, and only delivered to address specific customer issues. These releases are retired in a timely manner by the customer once the issue has been addressed in a standard release. +- InfluxData provides Support Services for the current and previous Minor Release (x.Y) including Maintenance Releases (x.y.Z) included in the respective Minor Release. +- When InfluxData releases a Major Release (X.y), InfluxData will provide Support Services for the current and preceding Major Release (X.y), including all Maintenance Releases (x.y.Z) included in the respective Minor Release that is available at least 12 months from the Major Release. + +For more information about supported 2.x releases, click [here](https://www.influxdata.com/legal/support-policy/). + +{{% note %}} +The link above contains the full legal description of the supported releases. +{{% /note %}} \ No newline at end of file diff --git a/content/influxdb/v2.1/reference/sample-data.md b/content/influxdb/v2.1/reference/sample-data.md new file mode 100644 index 0000000000..8ffc99d876 --- /dev/null +++ b/content/influxdb/v2.1/reference/sample-data.md @@ -0,0 +1,161 @@ +--- +title: Sample data +description: > + Use sample data to familiarize yourself with time series data and InfluxDB. + InfluxData provides many sample time series datasets to use with InfluxDB + and InfluxDB Cloud. +aliases: + - /influxdb/v2.1/write-data/sample-data/ +menu: influxdb_2_1_ref +weight: 7 +--- + +Use sample data to familiarize yourself with time series data and InfluxDB. +InfluxData provides many sample time series datasets to use with InfluxDB. +You can also use the [Flux InfluxDB sample package](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/sample/) +to view, download, and output sample datasets. + +- [Air sensor sample data](#air-sensor-sample-data) +- [Bird migration sample data](#bird-migration-sample-data) +- [NOAA sample data](#noaa-sample-data) + - [NOAA NDBC data](#noaa-ndbc-data) + - [NOAA water sample data](#noaa-water-sample-data) +- [USGS Earthquake data](#usgs-earthquake-data) + +## Air sensor sample data + +{{% caption %}} +**Size**: ~600 KB • **Updated**: every 15m +{{% /caption %}} + +Air sensor sample data represents an "Internet of Things" (IoT) use case by simulating +temperature, humidity, and carbon monoxide levels for multiple rooms in a building. + +To download and output the air sensor sample dataset, use the +[`sample.data()` function](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/sample/data/). + +```js +import "influxdata/influxdb/sample" + +sample.data(set: "airSensor") +``` + +#### Companion SQL sensor data +The air sensor sample dataset is paired with a relational SQL dataset with meta +information about sensors in each room. +These two sample datasets are used to demonstrate +[how to join time series data and relational data with Flux](/influxdb/v2.1/query-data/flux/sql/#join-sql-data-with-data-in-influxdb) +in the [Query SQL data sources](/influxdb/v2.1/query-data/flux/sql/) guide. + +Download SQL air sensor data + +## Bird migration sample data + +{{% caption %}} +**Size**: ~1.2 MB • **Updated**: N/A +{{% /caption %}} + +Bird migration sample data is adapted from the +[Movebank: Animal Tracking data set](https://www.kaggle.com/pulkit8595/movebank-animal-tracking) +and represents animal migratory movements throughout 2019. + +To download and output the bird migration sample dataset, use the +[`sample.data()` function](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/sample/data/). + +```js +import "influxdata/influxdb/sample" + +sample.data(set: "birdMigration") +``` + +The bird migration sample dataset is used in the [Work with geo-temporal data](/influxdb/v2.1/query-data/flux/geo/) +guide to demonstrate how to query and analyze geo-temporal data. + +## NOAA sample data + +There are two National Oceanic and Atmospheric Administration (NOAA) datasets +available to use with InfluxDB. + +- [NOAA NDBC data](#noaa-ndbc-data) +- [NOAA water sample data](#noaa-water-sample-data) + +### NOAA NDBC data + +{{% caption %}} +**Size**: ~1.3 MB • **Updated**: every 15m +{{% /caption %}} + +The **NOAA National Data Buoy Center (NDBC)** dataset provides the latest +observations from the NOAA NDBC network of buoys throughout the world. +Observations are updated approximately every 15 minutes. + +To download and output the most recent NOAA NDBC observations, use the +[`sample.data()` function](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/sample/data/). + +```js +import "influxdata/influxdb/sample" + +sample.data(set: "noaa") +``` + +{{% note %}} +#### Store historical NOAA NDBC data + +The **NOAA NDBC sample dataset** only returns the most recent observations; +not historical observations. +To regularly query and store NOAA NDBC observations, add the following as an +[InfluxDB task](/influxdb/v2.1/process-data/manage-tasks/). +Replace `example-org` and `example-bucket` with your organization name and the +name of the bucket to store data in. + +{{% get-shared-text "flux/noaa-ndbc-sample-task.md" %}} +{{% /note %}} + +### NOAA water sample data + +{{% caption %}} +**Size**: ~10 MB • **Updated**: N/A +{{% /caption %}} + +The **NOAA water sample dataset** is static dataset extracted from +[NOAA Center for Operational Oceanographic Products and Services](http://tidesandcurrents.noaa.gov/stations.html) data. +The sample dataset includes 15,258 observations of water levels (ft) collected every six minutes at two stations +(Santa Monica, CA (ID 9410840) and Coyote Creek, CA (ID 9414575)) over the period +from **August 18, 2015** through **September 18, 2015**. + +{{% note %}} +#### Store NOAA water sample data to avoid bandwidth usage +To avoid having to re-download this 10MB dataset every time you run a query, +we recommend that you [create a new bucket](/influxdb/v2.1/organizations/buckets/create-bucket/) +(`noaa`) and write the NOAA sample water data to it. + +```js +import "experimental/csv" + +csv.from(url: "https://influx-testdata.s3.amazonaws.com/noaa.csv") + |> to(bucket: "noaa", org: "example-org") +``` +{{% /note %}} + +The NOAA water sample dataset is used to demonstrate Flux queries in the +[Common queries](/influxdb/v2.1/query-data/common-queries/) and +[Common tasks](/influxdb/v2.1/process-data/common-tasks/) guides. + +## USGS Earthquake data + +{{% caption %}} +**Size**: ~6 MB • **Updated**: every 15m +{{% /caption %}} + +The United States Geological Survey (USGS) earthquake dataset contains observations +collected from USGS seismic sensors around the world over the last week. +Data is updated approximately every 15m. + +To download and output the last week of USGS seismic data, use the +[`sample.data()` function](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/sample/data/). + +```js +import "influxdata/influxdb/sample" + +sample.data(set: "usgs") +``` diff --git a/content/influxdb/v2.1/reference/syntax/_index.md b/content/influxdb/v2.1/reference/syntax/_index.md new file mode 100644 index 0000000000..3bd0b1f0c2 --- /dev/null +++ b/content/influxdb/v2.1/reference/syntax/_index.md @@ -0,0 +1,18 @@ +--- +title: InfluxDB syntaxes +description: > + InfluxDB uses a handful of languages and syntaxes to perform tasks such as + writing, querying, processing, and deleting data. +weight: 5 +menu: + influxdb_2_1_ref: + name: Syntax +influxdb/v2.1/tags: [syntax] +--- + +InfluxDB uses a handful of languages and syntaxes to perform tasks such as +writing, querying, processing, and deleting data. +The following articles provide information about the different syntaxes used with +InfluxDB and the contexts in which they're used: + +{{< children >}} diff --git a/content/influxdb/v2.1/reference/syntax/annotated-csv/_index.md b/content/influxdb/v2.1/reference/syntax/annotated-csv/_index.md new file mode 100644 index 0000000000..5d904f74f4 --- /dev/null +++ b/content/influxdb/v2.1/reference/syntax/annotated-csv/_index.md @@ -0,0 +1,311 @@ +--- +title: Annotated CSV +description: > + InfluxDB and Flux return query results in annotated CSV format. + You can also read annotated CSV directly from Flux with the `csv.from()` function, + write data to InfluxDB using annotated CSV and the `influx write` command, or upload a CSV file in the UI. +weight: 103 +menu: + influxdb_2_1_ref: + parent: Syntax +influxdb/v2.1/tags: [csv, syntax] +related: + - /{{< latest "flux" >}}/stdlib/csv/from/ + - /influxdb/v2.1/reference/syntax/annotated-csv/extended/ +--- + +InfluxDB and Flux return query results in annotated CSV format. +You can also read annotated CSV directly from Flux with the [`csv.from()` function](/{{< latest "flux" >}}/stdlib/csv/from/), write data to InfluxDB using annotated CSV and the `influx write` command, or [upload a CSV file](/influxdb/cloud/write-data/no-code/load-data/#load-data-by-uploading-a-csv-or-line-protocol-file) in the UI. + +CSV tables must be encoded in UTF-8 and Unicode Normal Form C as defined in [UAX15](http://www.unicode.org/reports/tr15/). +InfluxDB removes carriage returns before newline characters. + +## Examples + +In this topic, you'll find examples of valid CSV syntax for responses to the following query: + +```js +from(bucket:"mydb/autogen") + |> range(start:2018-05-08T20:50:00Z, stop:2018-05-08T20:51:00Z) + |> group(columns:["_start","_stop", "region", "host"]) + |> yield(name:"my-result") +``` + +## CSV response format + +Flux supports encodings listed below. + +### Tables + +A table may have the following rows and columns. + +#### Rows + +- **Annotation rows**: describe column properties. + +- **Header row**: defines column labels (one header row per table). + +- **Record row**: describes data in the table (one record per row). + +##### Example + +Encoding of a table with and without a header row. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Header row](#) +[Without header row](#) +{{% /code-tabs %}} + +{{% code-tab-content %}} +```sh +result,table,_start,_stop,_time,region,host,_value +my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 +my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 +my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 +``` +{{% /code-tab-content %}} + +{{% code-tab-content %}} +```sh +my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 +my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 +my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +#### Columns + +In addition to the data columns, a table may include the following columns: + +- **Annotation column**: Only used in annotation rows. Always the first column. + Displays the name of an annotation. Value can be empty or a supported [annotation](#annotations). + You'll notice a space for this column for the entire length of the table, + so rows appear to start with `,`. + +- **Result column**: Contains the name of the result specified by the query. + +- **Table column**: Contains a unique ID for each table in a result. + +### Multiple tables and results + +If a file or data stream contains multiple tables or results, the following requirements must be met: + +- A table column indicates which table a row belongs to. +- All rows in a table are contiguous. +- An empty row delimits a new table boundary in the following cases: + - Between tables in the same result that do not share a common table schema. + - Between concatenated CSV files. +- Each new table boundary starts with new annotation and header rows. + +##### Example + +Encoding of two tables in the same result with the same schema (header row) and different schema. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Same schema](#) +[Different schema](#) +{{% /code-tabs %}} + +{{% code-tab-content %}} +```sh +result,table,_start,_stop,_time,region,host,_value +my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 +my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 +my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 +my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,west,A,62.73 +my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,west,B,12.83 +my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,west,C,51.62 + +``` +{{% /code-tab-content %}} + +{{% code-tab-content %}} +```sh +,result,table,_start,_stop,_time,region,host,_value +,my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 +,my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 +,my-result,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 + +,result,table,_start,_stop,_time,location,device,min,max +,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,USA,5825,62.73,68.42 +,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,USA,2175,12.83,56.12 +,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,USA,6913,51.62,54.25 +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +## Dialect options + +Flux supports the following dialect options for `text/csv` format. + +| Option | Description | Default | +| :-------- | :--------- |:-------:| +| **header** | If true, the header row is included. | `true` | +| **delimiter** | Character used to delimit columns. | `,` | +| **quoteChar** | Character used to quote values containing the delimiter. | `"` | +| **annotations** | List of annotations to encode (datatype, group, or default). | `empty` | +| **commentPrefix** | String prefix to identify a comment. Always added to annotations. | `#` | + +## Annotations + +Annotation rows describe column properties, and start with `#` (or commentPrefix value). +The first column in an annotation row always contains the annotation name. +Subsequent columns contain annotation values as shown in the table below. + +| Annotation name | Values | Description | +|:-------- |:--------- | :------- | +| **datatype** | a [data type](#data-types) or [line protocol element](#line-protocol-elements) | Describes the type of data or which line protocol element the column represents. | +| **group** | boolean flag `true` or `false` | Indicates the column is part of the group key. | +| **default** | a value of the column's data type | Value to use for rows with an empty value. | + + +{{% note %}} +To encode a table with its [group key](/influxdb/v2.1/reference/glossary/#group-key), +the `datatype`, `group`, and `default` annotations must be included. +If a table has no rows, the `default` annotation provides the group key values. +{{% /note %}} + +## Data types + +| Datatype | Flux type | Description | +| :-------- | :--------- | :---------- | +| boolean | bool | "true" or "false" | +| unsignedLong | uint | unsigned 64-bit integer | +| long | int | signed 64-bit integer | +| double | float | IEEE-754 64-bit floating-point number | +| string | string | UTF-8 encoded string | +| base64Binary | bytes | base64 encoded sequence of bytes as defined in RFC 4648 | +| dateTime | time | instant in time, may be followed with a colon : and a description of the format (number, RFC3339, RFC3339Nano) | +| duration | duration | length of time represented as an unsigned 64-bit integer number of nanoseconds | + + +## Line protocol elements +The `datatype` annotation accepts [data types](#data-types) and **line protocol elements**. +Line protocol elements identify how columns are converted into line protocol when using the +[`influx write` command](/influxdb/v2.1/reference/cli/influx/write/) to write annotated CSV to InfluxDB. + +| Line protocol element | Description | +|:--------------------- |:----------- | +| `measurement` | column value is the measurement | +| `field` _(default)_ | column header is the field key, column value is the field value | +| `tag` | column header is the tag key, column value is the tag value | +| `time` | column value is the timestamp _(alias for `dateTime`)_ | +| `ignore` or`ignored` | column is ignored and not included in line protocol | + +### Mixing data types and line protocol elements +Columns with [data types](#data-types) (other than `dateTime`) in the +`#datatype` annotation are treated as **fields** when converted to line protocol. +Columns without a specified data type default to `field` when converted to line protocol +and **column values are left unmodified** in line protocol. +_See an example [below](#example-of-mixing-data-types-line-protocol-elements) and +[line protocol data types and format](/influxdb/v2.1/reference/syntax/line-protocol/#data-types-and-format)._ + +### Time columns +A column with `time` or `dateTime` `#datatype` annotations are used as the timestamp +when converted to line protocol. +If there are multiple `time` or `dateTime` columns, the last column (on the right) +is used as the timestamp in line protocol. +Other time columns are ignored and the `influx write` command outputs a warning. + +Time column values should be **Unix timestamps** (in an [accepted timestamp precision](/influxdb/v2.1/write-data/#timestamp-precision)), +**RFC3339**, or **RFC3339Nano**. + +##### Example line protocol elements in datatype annotation +``` +#datatype measurement,tag,tag,field,field,ignored,time +m,cpu,host,time_steal,usage_user,nothing,time +cpu,cpu1,host1,0,2.7,a,1482669077000000000 +cpu,cpu1,host2,0,2.2,b,1482669087000000000 +``` + +Resulting line protocol: + +``` +cpu,cpu=cpu1,host=host1 time_steal=0,usage_user=2.7 1482669077000000000 +cpu,cpu=cpu1,host=host2 time_steal=0,usage_user=2.2 1482669087000000000 +``` + +##### Example of mixing data types line protocol elements +``` +#datatype measurement,tag,string,double,boolean,long,unsignedLong,duration,dateTime +#default test,annotatedDatatypes,,,,,, +m,name,s,d,b,l,ul,dur,time +,,str1,1.0,true,1,1,1ms,1 +,,str2,2.0,false,2,2,2us,2020-01-11T10:10:10Z +``` + +Resulting line protocol: + +``` +test,name=annotatedDatatypes s="str1",d=1,b=true,l=1i,ul=1u,dur=1000000i 1 +test,name=annotatedDatatypes s="str2",d=2,b=false,l=2i,ul=2u,dur=2000i 1578737410000000000 +``` + +## Annotated CSV in Flux +Flux requires all annotation and header rows in annotated CSV. +The example below illustrates how to use the [`csv.from()` function](/{{< latest "flux" >}}/stdlib/csv/from/) +to read annotated CSV in Flux: + +```js +import "csv" + +csvData = "#datatype,string,long,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,string,string,double +#group,false,false,false,false,false,false,false,false +#default,,,,,,,, +,result,table,_start,_stop,_time,region,host,_value +,,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 +,,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 +,,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 +,,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,west,A,62.73 +,,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,west,B,12.83 +,,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,west,C,51.62 +" + +csv.from(csv: csvData) +``` + +{{% warn %}} +Flux only supports [data types](#data-types) in the `#datatype` annotation. +It does **does not** support [line protocol elements](#line-protocol-elements). +{{% /warn %}} + +## Errors + +If an error occurs during execution, a table returns with: + +- An error column that contains an error message. +- A reference column with a unique reference code to identify more information about the error. +- A second row with error properties. + +If an error occurs: + +- Before results materialize, the HTTP status code indicates an error. Error details are encoded in the csv table. +- After partial results are sent to the client, the error is encoded as the next table and remaining results are discarded. In this case, the HTTP status code remains 200 OK. + +##### Example + +Encoding for an error with the datatype annotation: + +``` +#datatype,string,long +,error,reference +,Failed to parse query,897 +``` + +Encoding for an error that occurs after a valid table has been encoded: + +``` +#datatype,string,long,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,string,string,double +,result,table,_start,_stop,_time,region,host,_value +,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,west,A,62.73 +,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,west,B,12.83 +,my-result,1,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,west,C,51.62 +``` + +``` +#datatype,string,long +,error,reference,query terminated: reached maximum allowed memory limits,576 +``` diff --git a/content/influxdb/v2.1/reference/syntax/annotated-csv/extended.md b/content/influxdb/v2.1/reference/syntax/annotated-csv/extended.md new file mode 100644 index 0000000000..263065ce55 --- /dev/null +++ b/content/influxdb/v2.1/reference/syntax/annotated-csv/extended.md @@ -0,0 +1,396 @@ +--- +title: Extended annotated CSV +description: > + Extended annotated CSV provides additional annotations and options that specify + how CSV data should be converted to [line protocol](/influxdb/v2.1/reference/syntax/line-protocol/) + and written to InfluxDB. +menu: + influxdb_2_1_ref: + name: Extended annotated CSV + parent: Annotated CSV +weight: 201 +influxdb/v2.1/tags: [csv, syntax, write] +related: + - /influxdb/v2.1/write-data/developer-tools/csv/ + - /influxdb/v2.1/reference/cli/influx/write/ + - /influxdb/v2.1/reference/syntax/line-protocol/ + - /influxdb/v2.1/reference/syntax/annotated-csv/ +--- + +**Extended annotated CSV** provides additional annotations and options that specify +how CSV data should be converted to [line protocol](/influxdb/v2.1/reference/syntax/line-protocol/) +and written to InfluxDB. +InfluxDB uses the [`csv2lp` library](https://github.com/influxdata/influxdb/tree/master/pkg/csv2lp) +to convert CSV into line protocol. +Extended annotated CSV supports all [Annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv/) +annotations. + +{{% warn %}} +The Flux [`csv.from` function](/{{< latest "flux" >}}/stdlib/csv/from/) only supports +[annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv/), not extended annotated CSV. +{{% /warn %}} + +To write data to InfluxDB, line protocol must include the following: + +- [measurement](/influxdb/v2.1/reference/syntax/line-protocol/#measurement) +- [field set](/influxdb/v2.1/reference/syntax/line-protocol/#field-set) +- [timestamp](/influxdb/v2.1/reference/syntax/line-protocol/#timestamp) _(Optional but recommended)_ +- [tag set](/influxdb/v2.1/reference/syntax/line-protocol/#tag-set) _(Optional)_ + +Extended CSV annotations identify the element of line protocol a column represents. + +## CSV Annotations +Extended annotated CSV extends and adds the following annotations: + +- [datatype](#datatype) +- [constant](#constant) +- [timezone](#timezone) +- [concat](#concat) + +### datatype +Use the `#datatype` annotation to specify the [line protocol element](/influxdb/v2.1/reference/syntax/line-protocol/#elements-of-line-protocol) +a column represents. +To explicitly define a column as a **field** of a specific data type, use the field +type in the annotation (for example: `string`, `double`, `long`, etc.). + +| Data type | Resulting line protocol | +|:---------- |:----------------------- | +| [measurement](#measurement) | Column is the **measurement** | +| [tag](#tag) | Column is a **tag** | +| [dateTime](#datetime) | Column is the **timestamp** | +| [field](#field) | Column is a **field** | +| [ignored](#ignored) | Column is ignored | +| [string](#string) | Column is a **string field** | +| [double](#double) | Column is a **float field** | +| [long](#long) | Column is an **integer field** | +| [unsignedLong](#unsignedlong) | Column is an **unsigned integer field** | +| [boolean](#boolean) | Column is a **boolean field** | + +#### measurement +Indicates the column is the **measurement**. + +#### tag +Indicates the column is a **tag**. +The **column label** is the **tag key**. +The **column value** is the **tag value**. + +#### dateTime +Indicates the column is the **timestamp**. +`time` is an alias for `dateTime`. +If the [timestamp format](#supported-timestamp-formats) includes a time zone, +the parsed timestamp includes the time zone offset. +By default, all timestamps are UTC. +You can also use the [`#timezone` annotation](#timezone) to adjust timestamps to +a specific time zone. + +{{% note %}} +There can only be **one** `dateTime` column. +{{% /note %}} + +The `influx write` command converts timestamps to [Unix timestamps](/influxdb/v2.1/reference/glossary/#unix-timestamp). +Append the timestamp format to the `dateTime` datatype with (`:`). + +```csv +#datatype dateTime:RFC3339 +#datatype dateTime:RFC3339Nano +#datatype dateTime:number +#datatype dateTime:2006-01-02 +``` + +##### Supported timestamp formats + +| Timestamp format | Description | Example | +|:---------------- |:----------- |:------- | +| **RFC3339** | RFC3339 timestamp | `2020-01-01T00:00:00Z` | +| **RFC3339Nano** | RFC3339 timestamp | `2020-01-01T00:00:00.000000000Z` | +| **number** | Unix timestamp | `1577836800000000000` | + +{{% note %}} +If using the `number` timestamp format and timestamps are **not in nanoseconds**, +use the [`influx write --precision` flag](/influxdb/v2.1/reference/cli/influx/write/#flags) +to specify the [timestamp precision](/influxdb/v2.1/reference/glossary/#precision). +{{% /note %}} + +##### Custom timestamp formats +To specify a custom timestamp format, use timestamp formats as described in the +[Go time package](https://golang.org/pkg/time). +For example: `2020-01-02`. + +#### field +Indicates the column is a **field**. +The **column label** is the **field key**. +The **column value** is the **field value**. + +{{% note %}} +With the `field` datatype, field values are copies **as-is** to line protocol. +For information about line protocol values and how they are written to InfluxDB, +see [Line protocol data types and formats](/influxdb/v2.1/reference/syntax/line-protocol/#data-types-and-format). +We generally recommend specifying the [field type](#field-types) in annotations. +{{% /note %}} + +#### ignored +The column is ignored and not written to InfluxDB. + +#### Field types +The column is a **field** of a specified type. +The **column label** is the **field key**. +The **column value** is the **field value**. + +- [string](#string) +- [double](#double) +- [long](#long) +- [unsignedLong](#unsignedlong) +- [boolean](#boolean) + +##### string +Column is a **[string](/influxdb/v2.1/reference/glossary/#string) field**. + +##### double +Column is a **[float](/influxdb/v2.1/reference/glossary/#float) field**. +By default, InfluxDB expects float values that use a period (`.`) to separate the +fraction from the whole number. +If column values include or use other separators, such as commas (`,`) to visually +separate large numbers into groups, specify the following **float separators**: + +- **fraction separator**: Separates the fraction from the whole number. +- **ignored separator**: Visually separates the whole number into groups but ignores + the separator when parsing the float value. + +Use the following syntax to specify **float separators**: + +```sh +# Syntax + + +# Example +., + +# With the float separators above +# 1,200,000.15 => 1200000.15 +``` + +Append **float separators** to the `double` datatype annotation with a colon (`:`). +For example: + +``` +#datatype "double:.," +``` + +{{% note %}} +If your **float separators** include a comma (`,`), wrap the column annotation in double +quotes (`""`) to prevent the comma from being parsed as a column separator or delimiter. +You can also [define a custom column separator](#define-custom-column-separator). +{{% /note %}} + +##### long +Column is an **[integer](/influxdb/v2.1/reference/glossary/#integer) field**. +If column values contain separators such as periods (`.`) or commas (`,`), specify +the following **integer separators**: + +- **fraction separator**: Separates the fraction from the whole number. + _**Integer values are truncated at the fraction separator when converted to line protocol.**_ +- **ignored separator**: Visually separates the whole number into groups but ignores + the separator when parsing the integer value. + +Use the following syntax to specify **integer separators**: + +```sh +# Syntax + + +# Example +., + +# With the integer separators above +# 1,200,000.00 => 1200000i +``` + +Append **integer separators** to the `long` datatype annotation with a colon (`:`). +For example: + +``` +#datatype "long:.," +``` + +{{% note %}} +If your **integer separators** include a comma (`,`), wrap the column annotation in double +quotes (`""`) to prevent the comma from being parsed as a column separator or delimiter. +You can also [define a custom column separator](#define-custom-column-separator). +{{% /note %}} + +##### unsignedLong +Column is an **[unsigned integer (uinteger)](/influxdb/v2.1/reference/glossary/#unsigned-integer) field**. +If column values contain separators such as periods (`.`) or commas (`,`), specify +the following **uinteger separators**: + +- **fraction separator**: Separates the fraction from the whole number. + _**Uinteger values are truncated at the fraction separator when converted to line protocol.**_ +- **ignored separator**: Visually separates the whole number into groups but ignores + the separator when parsing the uinteger value. + +Use the following syntax to specify **uinteger separators**: + +```sh +# Syntax + + +# Example +., + +# With the uinteger separators above +# 1,200,000.00 => 1200000u +``` + +Append **uinteger separators** to the `long` datatype annotation with a colon (`:`). +For example: + +``` +#datatype "usignedLong:.," +``` + +{{% note %}} +If your **uinteger separators** include a comma (`,`), wrap the column annotation in double +quotes (`""`) to prevent the comma from being parsed as a column separator or delimiter. +You can also [define a custom column separator](#define-custom-column-separator). +{{% /note %}} + +##### boolean +Column is a **[boolean](/influxdb/v2.1/reference/glossary/#boolean) field**. +If column values are not [supported boolean values](/influxdb/v2.1/reference/syntax/line-protocol/#boolean), +specify the **boolean format** with the following syntax: + +```sh +# Syntax +: + +# Example +y,Y,1:n,N,0 + +# With the boolean format above +# y => true, Y => true, 1 => true +# n => false, N => false, 0 => false +``` + +Append the **boolean format** to the `boolean` datatype annotation with a colon (`:`). +For example: + +``` +#datatype "boolean:y,Y:n,N" +``` + +{{% note %}} +If your **boolean format** contains commas (`,`), wrap the column annotation in double +quotes (`""`) to prevent the comma from being parsed as a column separator or delimiter. +You can also [define a custom column separator](#define-custom-column-separator). +{{% /note %}} + +### constant +Use the `#constant` annotation to define a constant column label and value for each row. +The `#constant` annotation provides a way to supply +[line protocol elements](/influxdb/v2.1/reference/syntax/line-protocol/#elements-of-line-protocol) +that don't exist in the CSV data. + +Use the following syntax to define constants: + +``` +#constant ,, +``` + +To provide multiple constants, include each `#constant` annotations on a separate line. + +``` +#constant measurement,m +#constant tag,dataSource,csv +``` + +{{% note %}} +For constants with `measurement` and `dateTime` datatypes, the second value in +the constant definition is the **column-value**. +{{% /note %}} + +### timezone +Use the `#timezone` annotation to update timestamps to a specific timezone. +By default, timestamps are parsed as UTC. +Use the `±HHmm` format to specify the timezone offset relative to UTC. + +### strict mode +Use the `:strict` keyword to indicate a loss of precision when parsing `long` or `unsignedLong` data types. +Turn on strict mode by using a column data type that ends with `strict`, such as `long:strict`. +When parsing `long` or `unsignedLong` value from a string value with fraction digits, the whole CSV row fails when in a strict mode. +A warning is printed when not in a strict mode, saying `line x: column y: '1.2' truncated to '1' to fit into long data type`. +For more information on strict parsing, see the [package documentation](https://github.com/influxdata/influxdb/tree/master/pkg/csv2lp). + +##### Timezone examples +| Timezone | Offset | +|:-------- | ------: | +| US Mountain Daylight Time | `-0600` | +| Central European Summer Time | `+0200` | +| Australia Eastern Standard Time | `+1000` | +| Apia Daylight Time | `+1400` | + +##### Timezone annotation example +``` +#timezone -0600 +``` + +### concat + +The `#concat` annotation adds a new column that is concatenated from existing columns according to bash-like string interpolation literal with variables referencing existing column labels. + +For example: + +``` +#concat,string,fullName,${firstName} ${lastName} +``` + +This is especially useful when constructing a timestamp from multiple columns. +For example, the following annotation will combine the given CSV columns into a timestamp: + +``` +#concat,dateTime:2006-01-02,${Year}-${Month}-${Day} + +Year,Month,Day,Hour,Minute,Second,Tag,Value +2020,05,22,00,00,00,test,0 +2020,05,22,00,05,00,test,1 +2020,05,22,00,10,00,test,2 +``` + +## Define custom column separator +If columns are delimited using a character other than a comma, use the `sep` +keyword to define a custom separator **in the first line of your CSV file**. + +``` +sep=; +``` + +## Annotation shorthand +Extended annotated CSV supports **annotation shorthand**. +Include the column label, datatype, and _(optional)_ default value in each column +header row using the following syntax: + +``` +|| +``` + +##### Example annotation shorthand +``` +m|measurement,location|tag|Hong Kong,temp|double,pm|long|0,time|dateTime:RFC3339 +weather,San Francisco,51.9,38,2020-01-01T00:00:00Z +weather,New York,18.2,,2020-01-01T00:00:00Z +weather,,53.6,171,2020-01-01T00:00:00Z +``` + +##### The shorthand explained +- The `m` column represents the **measurement** and has no default value. +- The `location` column is a **tag** with the default value, `Hong Kong`. +- The `temp` column is a **field** with **float** (`double`) values and no default value. +- The `pm` column is a **field** with **integer** (`long`) values and a default of `0`. +- The `time` column represents the **timestamp**, uses the **RFC3339** timestamp format, + and has no default value. + +##### Resulting line protocol +``` +weather,location=San\ Francisco temp=51.9,pm=38i 1577836800000000000 +weather,location=New\ York temp=18.2,pm=0i 1577836800000000000 +weather,location=Hong\ Kong temp=53.6,pm=171i 1577836800000000000 +``` diff --git a/content/influxdb/v2.1/reference/syntax/delete-predicate.md b/content/influxdb/v2.1/reference/syntax/delete-predicate.md new file mode 100644 index 0000000000..edf13c37d5 --- /dev/null +++ b/content/influxdb/v2.1/reference/syntax/delete-predicate.md @@ -0,0 +1,82 @@ +--- +title: Delete predicate syntax +list_title: Delete predicate +description: > + InfluxDB uses an InfluxQL-like predicate syntax to determine what data points to delete. +menu: + influxdb_2_1_ref: + parent: Syntax + name: Delete predicate +weight: 104 +influxdb/v2.1/tags: [syntax, delete] +related: + - /influxdb/v2.1/write-data/delete-data/ + - /influxdb/v2.1/reference/cli/influx/delete/ +--- + +InfluxDB uses an InfluxQL-like predicate syntax to determine what data +[points](/influxdb/v2.1/reference/glossary/#point) to delete. +InfluxDB uses the delete predicate to evaluate the [series keys](/influxdb/v2.1/reference/glossary/#series-key) +of points in the time range specified in the delete request. +Points with series keys that evaluate to `true` for the given predicate are deleted. +Points with series keys that evaluate to `false` are preserved. + +A delete predicate is comprised of one or more [predicate expressions](/influxdb/v2.1/reference/glossary/#predicate-expression). +The left operand of the predicate expression is the column name. +The right operand is the column value. +Operands are compared using [comparison operators](#comparison-operators). +Use [logical operators](#logical-operators) to combine two or more predicate expressions. + +##### Example delete predicate +```sql +key1="value1" AND key2="value" +``` +{{% note %}} +Predicate expressions can use any column or tag except `_time` or `_value`. +{{% /note %}} + +## Logical operators +Logical operators join two or more predicate expressions. + +| Operator | Description | +|:-------- |:----------- | +| `AND` | Both left and right operands must be `true` for the expression to be `true`. | + +## Comparison operators +Comparison operators compare left and right operands and return `true` or `false`. + +| Operator | Description | Example | Result | +|:-------- |:----------- |:-------: |:------:| +| `=` | Equal to | `"abc"="abc"` | `true` | + +## Delete predicate examples + +### Delete points with a specific measurement +The following will delete points in the `sensorData` measurement: + +```sql +_measurement="sensorData" +``` + + +### Delete points with a specific tag set +The following will delete points from the `prod-1.4` host in the `us-west` region: + +```sql +host="prod-1.4" AND region="us-west" +``` + +## Limitations +The delete predicate syntax has the following limitations. + +- Delete predicates do not support regular expressions. +- Delete predicates do not support the `OR` logical operator. +- Delete predicates only support equality (`=`), not inequality (`!=`). +- Delete predicates can use any column or tag except `_time` or `_value`. diff --git a/content/influxdb/v2.1/reference/syntax/flux/_index.md b/content/influxdb/v2.1/reference/syntax/flux/_index.md new file mode 100644 index 0000000000..c185a026d9 --- /dev/null +++ b/content/influxdb/v2.1/reference/syntax/flux/_index.md @@ -0,0 +1,29 @@ +--- +title: Flux syntax +list_title: Flux +description: > + Flux is a functional data scripting language designed for querying, analyzing, and acting on data. +menu: + influxdb_2_1_ref: + parent: Syntax + name: Flux + identifier: flux-syntax +weight: 101 +influxdb/v2.1/tags: [syntax, flux] +--- + +Flux is a functional data scripting language designed for querying, analyzing, and acting on data. + +## Flux documentation +View the [Flux documentation](/{{< latest "flux" >}}/) for more information about +the Flux syntax. + +- [Get started with Flux](/{{< latest "flux" >}}/get-started/) +- [Flux standard library](/{{< latest "flux" >}}/stdlib/) +- [Flux language specification](/{{< latest "flux" >}}/spec/) + +--- + +**The following provide information about Flux and InfluxDB:** + +{{< children >}} diff --git a/content/influxdb/v2.1/reference/syntax/flux/flux-vs-influxql.md b/content/influxdb/v2.1/reference/syntax/flux/flux-vs-influxql.md new file mode 100644 index 0000000000..f8a4f42009 --- /dev/null +++ b/content/influxdb/v2.1/reference/syntax/flux/flux-vs-influxql.md @@ -0,0 +1,405 @@ +--- +title: Flux vs InfluxQL +description: > + Flux is an alternative to InfluxQL and other SQL-like query languages for querying and analyzing data. + Learn about what's possible with Flux and how Flux compares to InfluxQL. +aliases: + - /influxdb/v2.1/reference/flux/flux-vs-influxql/ +menu: + influxdb_2_1_ref: + name: Flux vs InfluxQL + parent: flux-syntax + weight: 105 +--- + +Flux is an alternative to [InfluxQL](/influxdb/v2.1/query-data/influxql/) +and other SQL-like query languages for querying and analyzing data. +Flux uses functional language patterns that overcome many InfluxQL limitations. +Check out the following distinctions between Flux and InfluxQL: + +- [Tasks possible with Flux](#tasks-possible-with-flux) +- [InfluxQL and Flux parity](#influxql-and-flux-parity) + +## Tasks possible with Flux + +- [Joins](#joins) +- [Math across measurements](#math-across-measurements) +- [Sort by tags](#sort-by-tags) +- [Group by any column](#group-by-any-column) +- [Window by calendar months and years](#window-by-calendar-months-and-years) +- [Work with multiple data sources](#work-with-multiple-data-sources) +- [DatePart-like queries](#datepart-like-queries) +- [Pivot](#pivot) +- [Histograms](#histograms) +- [Covariance](#covariance) +- [Cast booleans to integers](#cast-booleans-to-integers) +- [String manipulation and data shaping](#string-manipulation-and-data-shaping) +- [Work with geo-temporal data](#work-with-geo-temporal-data) + +### Joins +InfluxQL has never supported joins. Although you can use a join in a [TICKscript](/{{< latest "kapacitor" >}}/tick/introduction/), +TICKscript's join capabilities are limited. +Flux's [`join()` function](/{{< latest "flux" >}}/stdlib/universe/join/) lets you +join data **from any bucket, any measurement, and on any columns** as long as +each data set includes the columns to join on. + +```js +dataStream1 = from(bucket: "example-bucket1") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "network" and + r._field == "bytes-transferred" + ) + +dataStream2 = from(bucket: "example-bucket2") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "httpd" and + r._field == "requests-per-sec" + ) + +join( + tables: {d1:dataStream1, d2:dataStream2}, + on: ["_time", "_stop", "_start", "host"] + ) +``` + +_For an in-depth walkthrough of using the `join()` function, see [how to join data with Flux](/influxdb/v2.1/query-data/flux/join/)._ + +### Math across measurements +Being able to perform joins across measurements lets you calculate +data from separate measurements. +The example below takes data from two measurements, `mem` and `processes`, +joins them, and then calculates the average amount of memory used per running process: + +```js +// Memory used (in bytes) +memUsed = from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used" + ) + +// Total processes running +procTotal = from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "processes" and + r._field == "total" + ) + +// Join memory used with total processes to calculate +// the average memory (in MB) used for running processes. +join( + tables: {mem:memUsed, proc:procTotal}, + on: ["_time", "_stop", "_start", "host"] + ) + |> map(fn: (r) => ({ + _time: r._time, + _value: (r._value_mem / r._value_proc) / 1000000 + }) +) +``` + +### Sort by tags +InfluxQL's sorting capabilities only let you control the +sort order of `time` using the `ORDER BY time` clause. +The Flux [`sort()` function](/{{< latest "flux" >}}/stdlib/universe/sort) +sorts records based on a list of columns. +Depending on the column type, Flux sorts records lexicographically, numerically, or chronologically. + +```js +from(bucket:"example-bucket") + |> range(start: -12h) + |> filter(fn: (r) => + r._measurement == "system" and + r._field == "uptime" + ) + |> sort(columns:["region", "host", "_value"]) +``` + +### Group by any column +InfluxQL lets you group by tags or time intervals only. +Flux lets you group data by any column, including `_value`. +Use the Flux [`group()` function](/{{< latest "flux" >}}/stdlib/universe/group/) +to define which columns to group data by. + +```js +from(bucket:"example-bucket") + |> range(start: -12h) + |> filter(fn: (r) => r._measurement == "system" and r._field == "uptime" ) + |> group(columns:["host", "_value"]) +``` + +### Window by calendar months and years +InfluxQL does not support windowing data by calendar months and years due to their varied lengths. +Flux supports calendar month and year duration units (`1mo`, `1y`) and lets you +window and aggregate data by calendar month and year. + +```js +from(bucket:"example-bucket") + |> range(start:-1y) + |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent" ) + |> aggregateWindow(every: 1mo, fn: mean) +``` + +### Work with multiple data sources +InfluxQL can only query data stored in InfluxDB. +Flux can query data from other data sources such as CSV, PostgreSQL, MySQL, Google BigTable, and more. +Join that data with data in InfluxDB to enrich query results. + +- [Flux CSV package](/{{< latest "flux" >}}/stdlib/csv/) +- [Flux SQL package](/{{< latest "flux" >}}/stdlib/sql/) +- [Flux BigTable package](/{{< latest "flux" >}}/stdlib/experimental/bigtable/) + + +```js +import "csv" +import "sql" + +csvData = csv.from(csv: rawCSV) +sqlData = sql.from( + driverName: "postgres", + dataSourceName: "postgresql://user:password@localhost", + query:"SELECT * FROM example_table" +) +data = from(bucket: "example-bucket") + |> range(start: -24h) + |> filter(fn: (r) => r._measurement == "sensor") + +auxData = join(tables: {csv: csvData, sql: sqlData}, on: ["sensor_id"]) +enrichedData = join(tables: {data: data, aux: auxData}, on: ["sensor_id"]) + +enrichedData + |> yield(name: "enriched_data") +``` + +_For an in-depth walkthrough of querying SQL data, see [Query SQL data sources](/influxdb/v2.1/query-data/flux/sql/)._ + +### DatePart-like queries +InfluxQL doesn't support DatePart-like queries that only return results during specified hours of the day. +The Flux [`hourSelection` function](/{{< latest "flux" >}}/stdlib/universe/hourselection/) +returns only data with time values in a specified hour range. + +```js +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r.cpu == "cpu-total" + ) + |> hourSelection(start: 9, stop: 17) +``` + +### Pivot +Pivoting data tables isn't supported in InfluxQL. +Use the Flux [`pivot()` function](/{{< latest "flux" >}}/stdlib/universe/pivot) +to pivot data tables by `rowKey`, `columnKey`, and `valueColumn` parameters. + +```js +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r.cpu == "cpu-total" + ) + |> pivot( + rowKey:["_time"], + columnKey: ["_field"], + valueColumn: "_value" + ) +``` + +### Histograms +Generating histograms isn't supported in InfluxQL. +Use the Flux [`histogram()` function](/{{< latest "flux" >}}/stdlib/universe/histogram) to +generate a cumulative histogram. + +```js +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> histogram( + buckets: [10, 20, 30, 40, 50, 60, 70, 80, 90, 100] + ) +``` + +_For more examples, see [how to create histograms with Flux](/influxdb/v2.1/query-data/flux/histograms/)._ + +### Covariance +Flux provides functions for simple covariance calculations. +Use the [`covariance()` function](/{{< latest "flux" >}}/stdlib/universe/covariance) +to calculate the covariance between two columns and the [`cov()` function](/{{< latest "flux" >}}/stdlib/universe/cov) +to calculate the covariance between two data streams. + +###### Covariance between two columns +```js +from(bucket: "example-bucket") + |> range(start:-5m) + |> covariance(columns: ["x", "y"]) +``` + +###### Covariance between two streams of data +```js +table1 = from(bucket: "example-bucket") + |> range(start: -15m) + |> filter(fn: (r) => + r._measurement == "measurement_1" + ) + +table2 = from(bucket: "example-bucket") + |> range(start: -15m) + |> filter(fn: (r) => + r._measurement == "measurement_2" + ) + +cov(x: table1, y: table2, on: ["_time", "_field"]) +``` + +### Cast booleans to integers +InfluxQL supports type casting for numeric data types (floats to integers and vice versa) only. +Use [Flux type conversion functions](/{{< latest "flux" >}}/function-types/#type-conversions) +to perform many more type conversions, including casting boolean values to integers. + +##### Cast boolean field values to integers +```js +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "m" and + r._field == "bool_field" + ) + |> toInt() +``` + +### String manipulation and data shaping +InfluxQL doesn't support string manipulation when querying data. +Use [Flux Strings package](/{{< latest "flux" >}}/stdlib/strings/) functions to operate on string data. +Combine functions in this package with the [`map()` function](/{{< latest "flux" >}}/stdlib/universe/map/) to perform operations like sanitizing and normalizing strings. + +```js +import "strings" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "weather" and + r._field == "temp" + ) + |> map(fn: (r) => ({ + r with + location: strings.toTitle(v: r.location), + sensor: strings.replaceAll(v: r.sensor, t: " ", u: "-"), + status: strings.substring(v: r.status, start: 0, end: 8) + })) +``` + +### Work with geo-temporal data +InfluxQL doesn't support working with geo-temporal data. +The [Flux Geo package](/{{< latest "flux" >}}/stdlib/experimental/geo/) is a collection of functions that +let you shape, filter, and group geo-temporal data. + +```js +import "experimental/geo" + +from(bucket: "geo/autogen") + |> range(start: -1w) + |> filter(fn: (r) => r._measurement == "taxi") + |> geo.shapeData(latField: "latitude", lonField: "longitude", level: 20) + |> geo.filterRows( + region: {lat: 40.69335938, lon: -73.30078125, radius: 20.0}, + strict: true + ) + |> geo.asTracks(groupBy: ["fare-id"]) +``` + + +## InfluxQL and Flux parity +We're continuing to add functions to complete parity between Flux and InfluxQL. +The table below shows InfluxQL statements, clauses, and functions along with their equivalent Flux functions. + +_For a complete list of Flux functions, [view all Flux functions](/{{< latest "flux" >}}/stdlib/all-functions/)._ + +| InfluxQL | Flux Functions | +| :------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [SELECT](/{{< latest "influxdb" "v1" >}}/query_language/explore-data/#the-basic-select-statement) | [filter()](/{{< latest "flux" >}}/stdlib/universe/filter/) | +| [WHERE](/{{< latest "influxdb" "v1" >}}/query_language/explore-data/#the-where-clause) | [filter()](/{{< latest "flux" >}}/stdlib/universe/filter/), [range()](/{{< latest "flux" >}}/stdlib/universe/range/) | +| [GROUP BY](/{{< latest "influxdb" "v1" >}}/query_language/explore-data/#the-group-by-clause) | [group()](/{{< latest "flux" >}}/stdlib/universe/group/) | +| [INTO](/{{< latest "influxdb" "v1" >}}/query_language/explore-data/#the-into-clause) | [to()](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/to/) | +| [ORDER BY](/{{< latest "influxdb" "v1" >}}/query_language/explore-data/#order-by-time-desc) | [sort()](/{{< latest "flux" >}}/stdlib/universe/sort/) | +| [LIMIT](/{{< latest "influxdb" "v1" >}}/query_language/explore-data/#the-limit-clause) | [limit()](/{{< latest "flux" >}}/stdlib/universe/limit/) | +| [SLIMIT](/{{< latest "influxdb" "v1" >}}/query_language/explore-data/#the-slimit-clause) | -- | +| [OFFSET](/{{< latest "influxdb" "v1" >}}/query_language/explore-data/#the-offset-clause) | -- | +| [SOFFSET](/{{< latest "influxdb" "v1" >}}/query_language/explore-data/#the-soffset-clause) | -- | +| [SHOW DATABASES](/{{< latest "influxdb" "v1" >}}/query_language/explore-schema/#show-databases) | [buckets()](/{{< latest "flux" >}}/stdlib/universe/buckets/) | +| [SHOW MEASUREMENTS](/{{< latest "influxdb" "v1" >}}/query_language/explore-schema/#show-measurements) | [schema.measurements](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/measurements) | +| [SHOW FIELD KEYS](/{{< latest "influxdb" "v1" >}}/query_language/explore-schema/#show-field-keys) | [keys()](/{{< latest "flux" >}}/stdlib/universe/keys/) | +| [SHOW RETENTION POLICIES](/{{< latest "influxdb" "v1" >}}/query_language/explore-schema/#show-retention-policies) | [buckets()](/{{< latest "flux" >}}/stdlib/universe/buckets/) | +| [SHOW TAG KEYS](/{{< latest "influxdb" "v1" >}}/query_language/explore-schema/#show-tag-keys) | [schema.tagKeys()](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/tagkeys), [schema.measurementTagKeys()](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/measurementtagkeys) | +| [SHOW TAG VALUES](/{{< latest "influxdb" "v1" >}}/query_language/explore-schema/#show-tag-values) | [schema.tagValues()](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/tagvalues), [schema.measurementTagValues()](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/measurementtagvalues) | +| [SHOW SERIES](/{{< latest "influxdb" "v1" >}}/query_language/explore-schema/#show-series) | -- | +| [CREATE DATABASE](/{{< latest "influxdb" "v1" >}}/query_language/manage-database/#create-database) | N/A | +| [DROP DATABASE](/{{< latest "influxdb" "v1" >}}/query_language/manage-database/#delete-a-database-with-drop-database) | N/A | +| [DROP SERIES](/{{< latest "influxdb" "v1" >}}/query_language/manage-database/#drop-series-from-the-index-with-drop-serie) | N/A | +| [DELETE](/{{< latest "influxdb" "v1" >}}/query_language/manage-database/#delete-series-with-delete) | N/A | +| [DROP MEASUREMENT](/{{< latest "influxdb" "v1" >}}/query_language/manage-database/#delete-measurements-with-drop-measurement) | N/A | +| [DROP SHARD](/{{< latest "influxdb" "v1" >}}/query_language/manage-database/#delete-a-shard-with-drop-shard) | N/A | +| [CREATE RETENTION POLICY](/{{< latest "influxdb" "v1" >}}/query_language/manage-database/#create-retention-policies-with-create-retention-policy) | N/A | +| [ALTER RETENTION POLICY](/{{< latest "influxdb" "v1" >}}/query_language/manage-database/#modify-retention-policies-with-alter-retention-policy) | N/A | +| [DROP RETENTION POLICY](/{{< latest "influxdb" "v1" >}}/query_language/manage-database/#delete-retention-policies-with-drop-retention-policy) | N/A | +| [COUNT](/{{< latest "influxdb" "v1" >}}/query_language/functions#count) | [count()](/{{< latest "flux" >}}/stdlib/universe/count/) | +| [DISTINCT](/{{< latest "influxdb" "v1" >}}/query_language/functions#distinct) | [distinct()](/{{< latest "flux" >}}/stdlib/universe/distinct/) | +| [INTEGRAL](/{{< latest "influxdb" "v1" >}}/query_language/functions#integral) | [integral()](/{{< latest "flux" >}}/stdlib/universe/integral/) | +| [MEAN](/{{< latest "influxdb" "v1" >}}/query_language/functions#mean) | [mean()](/{{< latest "flux" >}}/stdlib/universe/mean/) | +| [MEDIAN](/{{< latest "influxdb" "v1" >}}/query_language/functions#median) | [median()](/{{< latest "flux" >}}/stdlib/universe/median/) | +| [MODE](/{{< latest "influxdb" "v1" >}}/query_language/functions#mode) | [mode()](/{{< latest "flux" >}}/stdlib/universe/mode/) | +| [SPREAD](/{{< latest "influxdb" "v1" >}}/query_language/functions#spread) | [spread()](/{{< latest "flux" >}}/stdlib/universe/spread/) | +| [STDDEV](/{{< latest "influxdb" "v1" >}}/query_language/functions#stddev) | [stddev()](/{{< latest "flux" >}}/stdlib/universe/stddev/) | +| [SUM](/{{< latest "influxdb" "v1" >}}/query_language/functions#sum) | [sum()](/{{< latest "flux" >}}/stdlib/universe/sum/) | +| [BOTTOM](/{{< latest "influxdb" "v1" >}}/query_language/functions#bottom) | [bottom()](/{{< latest "flux" >}}/stdlib/universe/bottom/) | +| [FIRST](/{{< latest "influxdb" "v1" >}}/query_language/functions#first) | [first()](/{{< latest "flux" >}}/stdlib/universe/first/) | +| [LAST](/{{< latest "influxdb" "v1" >}}/query_language/functions#last) | [last()](/{{< latest "flux" >}}/stdlib/universe/last/) | +| [MAX](/{{< latest "influxdb" "v1" >}}/query_language/functions#max) | [max()](/{{< latest "flux" >}}/stdlib/universe/max/) | +| [MIN](/{{< latest "influxdb" "v1" >}}/query_language/functions#min) | [min()](/{{< latest "flux" >}}/stdlib/universe/min/) | +| [PERCENTILE](/{{< latest "influxdb" "v1" >}}/query_language/functions#percentile) | [quantile()](/{{< latest "flux" >}}/stdlib/universe/quantile/) | +| [SAMPLE](/{{< latest "influxdb" "v1" >}}/query_language/functions#sample) | [sample()](/{{< latest "flux" >}}/stdlib/universe/sample/) | +| [TOP](/{{< latest "influxdb" "v1" >}}/query_language/functions#top) | [top()](/{{< latest "flux" >}}/stdlib/universe/top/) | +| [ABS](/{{< latest "influxdb" "v1" >}}/query_language/functions#abs) | [math.abs()](/{{< latest "flux" >}}/stdlib/math/abs/) | +| [ACOS](/{{< latest "influxdb" "v1" >}}/query_language/functions#acos) | [math.acos()](/{{< latest "flux" >}}/stdlib/math/acos/) | +| [ASIN](/{{< latest "influxdb" "v1" >}}/query_language/functions#asin) | [math.asin()](/{{< latest "flux" >}}/stdlib/math/asin/) | +| [ATAN](/{{< latest "influxdb" "v1" >}}/query_language/functions#atan) | [math.atan()](/{{< latest "flux" >}}/stdlib/math/atan/) | +| [ATAN2](/{{< latest "influxdb" "v1" >}}/query_language/functions#atan2) | [math.atan2()](/{{< latest "flux" >}}/stdlib/math/atan2/) | +| [CEIL](/{{< latest "influxdb" "v1" >}}/query_language/functions#ceil) | [math.ceil()](/{{< latest "flux" >}}/stdlib/math/ceil/) | +| [COS](/{{< latest "influxdb" "v1" >}}/query_language/functions#cos) | [math.cos()](/{{< latest "flux" >}}/stdlib/math/cos/) | +| [CUMULATIVE_SUM](/{{< latest "influxdb" "v1" >}}/query_language/functions#cumulative-sum) | [cumulativeSum()](/{{< latest "flux" >}}/stdlib/universe/cumulativesum/) | +| [DERIVATIVE](/{{< latest "influxdb" "v1" >}}/query_language/functions#derivative) | [derivative()](/{{< latest "flux" >}}/stdlib/universe/derivative/) | +| [DIFFERENCE](/{{< latest "influxdb" "v1" >}}/query_language/functions#difference) | [difference()](/{{< latest "flux" >}}/stdlib/universe/difference/) | +| [ELAPSED](/{{< latest "influxdb" "v1" >}}/query_language/functions#elapsed) | [elapsed()](/{{< latest "flux" >}}/stdlib/universe/elapsed/) | +| [EXP](/{{< latest "influxdb" "v1" >}}/query_language/functions#exp) | [math.exp()](/{{< latest "flux" >}}/stdlib/math/exp/) | +| [FLOOR](/{{< latest "influxdb" "v1" >}}/query_language/functions#floor) | [math.floor()](/{{< latest "flux" >}}/stdlib/math/floor/) | +| [HISTOGRAM](/{{< latest "influxdb" "v1" >}}/query_language/functions#histogram) | [histogram()](/{{< latest "flux" >}}/stdlib/universe/histogram/) | +| [LN](/{{< latest "influxdb" "v1" >}}/query_language/functions#ln) | [math.log()](/{{< latest "flux" >}}/stdlib/math/log/) | +| [LOG](/{{< latest "influxdb" "v1" >}}/query_language/functions#log) | [math.logb()](/{{< latest "flux" >}}/stdlib/math/logb/) | +| [LOG2](/{{< latest "influxdb" "v1" >}}/query_language/functions#log2) | [math.log2()](/{{< latest "flux" >}}/stdlib/math/log2/) | +| [LOG10](/{{< latest "influxdb" "v1" >}}/query_language/functions#logt10) | [math.log10()](/{{< latest "flux" >}}/stdlib/math/log10/) | +| [MOVING_AVERAGE](/{{< latest "influxdb" "v1" >}}/query_language/functions#moving-average) | [movingAverage()](/{{< latest "flux" >}}/stdlib/universe/movingaverage/) | +| [NON_NEGATIVE_DERIVATIVE](/{{< latest "influxdb" "v1" >}}/query_language/functions#non-negative-derivative) | [derivative(nonNegative:true)](/{{< latest "flux" >}}/stdlib/universe/derivative/) | +| [NON_NEGATIVE_DIFFERENCE](/{{< latest "influxdb" "v1" >}}/query_language/functions#non-negative-difference) | [difference(nonNegative:true)](/{{< latest "flux" >}}/stdlib/universe/derivative/) | +| [POW](/{{< latest "influxdb" "v1" >}}/query_language/functions#pow) | [math.pow()](/{{< latest "flux" >}}/stdlib/math/pow/) | +| [ROUND](/{{< latest "influxdb" "v1" >}}/query_language/functions#round) | [math.round()](/{{< latest "flux" >}}/stdlib/math/round/) | +| [SIN](/{{< latest "influxdb" "v1" >}}/query_language/functions#sin) | [math.sin()](/{{< latest "flux" >}}/stdlib/math/sin/) | +| [SQRT](/{{< latest "influxdb" "v1" >}}/query_language/functions#sqrt) | [math.sqrt()](/{{< latest "flux" >}}/stdlib/math/sqrt/) | +| [TAN](/{{< latest "influxdb" "v1" >}}/query_language/functions#tan) | [math.tan()](/{{< latest "flux" >}}/stdlib/math/tan/) | +| [HOLT_WINTERS](/{{< latest "influxdb" "v1" >}}/query_language/functions#holt-winters) | [holtWinters()](/{{< latest "flux" >}}/stdlib/universe/holtwinters/) | +| [CHANDE_MOMENTUM_OSCILLATOR](/{{< latest "influxdb" "v1" >}}/query_language/functions#chande-momentum-oscillator) | [chandeMomentumOscillator()](/{{< latest "flux" >}}/stdlib/universe/chandemomentumoscillator/) | +| [EXPONENTIAL_MOVING_AVERAGE](/{{< latest "influxdb" "v1" >}}/query_language/functions#exponential-moving-average) | [exponentialMovingAverage()](/{{< latest "flux" >}}/stdlib/universe/exponentialmovingaverage/) | +| [DOUBLE_EXPONENTIAL_MOVING_AVERAGE](/{{< latest "influxdb" "v1" >}}/query_language/functions#double-exponential-moving-average) | [doubleEMA()](/{{< latest "flux" >}}/stdlib/universe/doubleema/) | +| [KAUFMANS_EFFICIENCY_RATIO](/{{< latest "influxdb" "v1" >}}/query_language/functions#kaufmans-efficiency-ratio) | [kaufmansER()](/{{< latest "flux" >}}/stdlib/universe/kaufmanser/) | +| [KAUFMANS_ADAPTIVE_MOVING_AVERAGE](/{{< latest "influxdb" "v1" >}}/query_language/functions#kaufmans-adaptive-moving-average) | [kaufmansAMA()](/{{< latest "flux" >}}/stdlib/universe/kaufmansama/) | +| [TRIPLE_EXPONENTIAL_MOVING_AVERAGE](/{{< latest "influxdb" "v1" >}}/query_language/functions#triple-exponential-moving-average) | [tripleEMA()](/{{< latest "flux" >}}/stdlib/universe/tripleema/) | +| [TRIPLE_EXPONENTIAL_DERIVATIVE](/{{< latest "influxdb" "v1" >}}/query_language/functions#triple-exponential-derivative) | [tripleExponentialDerivative()](/{{< latest "flux" >}}/stdlib/universe/tripleexponentialderivative/) | +| [RELATIVE_STRENGTH_INDEX](/{{< latest "influxdb" "v1" >}}/query_language/functions#relative-strength-index) | [relativeStrengthIndex()](/{{< latest "flux" >}}/stdlib/universe/relativestrengthindex/) | diff --git a/content/influxdb/v2.1/reference/syntax/line-protocol.md b/content/influxdb/v2.1/reference/syntax/line-protocol.md new file mode 100644 index 0000000000..c2acbec5ef --- /dev/null +++ b/content/influxdb/v2.1/reference/syntax/line-protocol.md @@ -0,0 +1,283 @@ +--- +title: Line protocol +description: > + InfluxDB uses line protocol to write data points. + It is a text-based format that provides the measurement, tag set, field set, and timestamp of a data point. +menu: + influxdb_2_1_ref: + parent: Syntax +weight: 102 +influxdb/v2.1/tags: [write, line protocol, syntax] +aliases: + - /influxdb/v2.1/reference/line-protocol + - /influxdb/v2.1/write_protocols/line_protocol_tutorial/ +related: + - /influxdb/v2.1/write-data/ +--- + +InfluxDB uses line protocol to write data points. +It is a text-based format that provides the measurement, tag set, field set, and timestamp of a data point. + +- [Elements of line protocol](#elements-of-line-protocol) +- [Data types and format](#data-types-and-format) +- [Quotes](#quotes) +- [Special characters](#special-characters) +- [Comments](#comments) +- [Naming restrictions](#naming-restrictions) +- [Duplicate points](#duplicate-points) + +```js +// Syntax +[,=[,=]] =[,=] [] + +// Example +myMeasurement,tag1=value1,tag2=value2 fieldKey="fieldValue" 1556813561098000000 +``` + +Lines separated by the newline character `\n` represent a single point +in InfluxDB. Line protocol is whitespace sensitive. + +{{% note %}} +Line protocol does not support the newline character `\n` in tag or field values. +{{% /note %}} + +## Elements of line protocol + +``` +measurementName,tagKey=tagValue fieldKey="fieldValue" 1465839830100400200 +--------------- --------------- --------------------- ------------------- + | | | | + Measurement Tag set Field set Timestamp +``` + +### Measurement +({{< req >}}) +The measurement name. +InfluxDB accepts one measurement per point. +_Measurement names are case-sensitive and subject to [naming restrictions](#naming-restrictions)._ + +_**Data type:** [String](#string)_ + + +### Tag set +_**Optional**_ – +All tag key-value pairs for the point. +Key-value relationships are denoted with the `=` operand. +Multiple tag key-value pairs are comma-delimited. +_Tag keys and tag values are case-sensitive. +Tag keys are subject to [naming restrictions](#naming-restrictions)._ + +_**Key data type:** [String](#string)_ +_**Value data type:** [String](#string)_ + +### Field set +({{< req >}}) +All field key-value pairs for the point. +Points must have at least one field. +_Field keys and string values are case-sensitive. +Field keys are subject to [naming restrictions](#naming-restrictions)._ + +_**Key data type:** [String](#string)_ +_**Value data type:** [Float](#float) | [Integer](#integer) | [UInteger](#uinteger) | [String](#string) | [Boolean](#boolean)_ + +{{% note %}} +_Always double quote string field values. More on quotes [below](#quotes)._ + +```sh +measurementName fieldKey="field string value" 1556813561098000000 +``` +{{% /note %}} + +### Timestamp +_**Optional**_ – +The [unix timestamp](/influxdb/v2.1/reference/glossary/#unix-timestamp) for the data point. +InfluxDB accepts one timestamp per point. +If no timestamp is provided, InfluxDB uses the system time (UTC) of its host machine. + +_**Data type:** [Unix timestamp](#unix-timestamp)_ + +{{% note %}} +#### Important notes about timestamps +- To ensure a data point includes the time a metric is observed (not received by InfluxDB), + include the timestamp. +- If your timestamps are not in nanoseconds, specify the precision of your timestamps + when [writing the data to InfluxDB](/influxdb/v2.1/write-data/#timestamp-precision). +{{% /note %}} + +### Whitespace +Whitespace in line protocol determines how InfluxDB interprets the data point. +The **first unescaped space** delimits the measurement and the tag set from the field set. +The **second unescaped space** delimits the field set from the timestamp. + +``` +measurementName,tagKey=tagValue fieldKey="fieldValue" 1465839830100400200 + | | + 1st space 2nd space +``` + +## Data types and format + +### Float +IEEE-754 64-bit floating-point numbers. +Default numerical type. +_InfluxDB supports scientific notation in float field values._ + +##### Float field value examples +```js +myMeasurement fieldKey=1.0 +myMeasurement fieldKey=1 +myMeasurement fieldKey=-1.234456e+78 +``` + +### Integer +Signed 64-bit integers. +Trailing `i` on the number specifies an integer. + +| Minimum integer | Maximum integer | +| --------------- | --------------- | +| `-9223372036854775808i` | `9223372036854775807i` | + +##### Integer field value examples +```js +myMeasurement fieldKey=1i +myMeasurement fieldKey=12485903i +myMeasurement fieldKey=-12485903i +``` + +### UInteger +Unsigned 64-bit integers. +Trailing `u` on the number specifies an unsigned integer. + +| Minimum uinteger | Maximum uinteger | +| ---------------- | ---------------- | +| `0u` | `18446744073709551615u` | + +##### UInteger field value examples +```js +myMeasurement fieldKey=1u +myMeasurement fieldKey=12485903u +``` + +### String +Plain text string. +Length limit 64KB. + +##### String example +```sh +# String measurement name, field key, and field value +myMeasurement fieldKey="this is a string" +``` + +### Boolean +Stores `true` or `false` values. + +| Boolean value | Accepted syntax | +|:-------------:|:--------------- | +| True | `t`, `T`, `true`, `True`, `TRUE` | +| False | `f`, `F`, `false`, `False`, `FALSE` | + +##### Boolean field value examples +```js +myMeasurement fieldKey=true +myMeasurement fieldKey=false +myMeasurement fieldKey=t +myMeasurement fieldKey=f +myMeasurement fieldKey=TRUE +myMeasurement fieldKey=FALSE +``` + +{{% note %}} +Do not quote boolean field values. +Quoted field values are interpreted as strings. +{{% /note %}} + +### Unix timestamp +Unix timestamp in a [specified precision](/influxdb/v2.1/reference/glossary/#unix-timestamp). +Default precision is nanoseconds (`ns`). + +| Minimum timestamp | Maximum timestamp | +| ----------------- | ----------------- | +| `-9223372036854775806` | `9223372036854775806` | + +##### Unix timestamp example +```js +myMeasurementName fieldKey="fieldValue" 1556813561098000000 +``` + +## Quotes +Line protocol supports single and double quotes as described in the following table: + +| Element | Double quotes | Single quotes | +| :------ | :------------: |:-------------: | +| Measurement | _Limited_ * | _Limited_ * | +| Tag key | _Limited_ * | _Limited_ * | +| Tag value | _Limited_ * | _Limited_ * | +| Field key | _Limited_ * | _Limited_ * | +| Field value | **Strings only** | Never | +| Timestamp | Never | Never | + +\* _Line protocol accepts double and single quotes in +measurement names, tag keys, tag values, and field keys, but interprets them as +part of the name, key, or value._ + +## Special Characters +Line protocol supports special characters in [string elements](#string). +In the following contexts, it requires escaping certain characters with a backslash (`\`): + +| Element | Escape characters | +|:------- |:----------------- | +| Measurement | Comma, Space | +| Tag key | Comma, Equals Sign, Space | +| Tag value | Comma, Equals Sign, Space | +| Field key | Comma, Equals Sign, Space | +| Field value | Double quote, Backslash | + +You do not need to escape other special characters. + +##### Examples of special characters in line protocol +```sh +# Measurement name with spaces +my\ Measurement fieldKey="string value" + +# Double quotes in a string field value +myMeasurement fieldKey="\"string\" within a string" + +# Tag keys and values with spaces +myMeasurement,tag\ Key1=tag\ Value1,tag\ Key2=tag\ Value2 fieldKey=100 + +# Emojis +myMeasurement,tagKey=🍭 fieldKey="Launch 🚀" 1556813561098000000 +``` + +### Escaping backslashes +Line protocol supports both literal backslashes and backslashes as an escape character. +With two contiguous backslashes, the first is interpreted as an escape character. +For example: + +| Backslashes | Interpreted as | +|:-----------:|:-------------:| +| `\` | `\` | +| `\\` | `\` | +| `\\\` | `\\` | +| `\\\\` | `\\` | +| `\\\\\` | `\\\` | +| `\\\\\\` | `\\\` | + +## Comments +Line protocol interprets `#` at the beginning of a line as a comment character +and ignores all subsequent characters until the next newline `\n`. + +```sh +# This is a comment +myMeasurement fieldKey="string value" 1556813561098000000 +``` + +## Naming restrictions +Measurement names, tag keys, and field keys cannot begin with an underscore `_`. +The `_` namespace is reserved for InfluxDB system use. + +## Duplicate points +A point is uniquely identified by the measurement name, tag set, and timestamp. +If you submit line protocol with the same measurement, tag set, and timestamp, +but with a different field set, the field set becomes the union of the old +field set and the new field set, where any conflicts favor the new field set. diff --git a/content/influxdb/v2.1/reference/telegraf-plugins.md b/content/influxdb/v2.1/reference/telegraf-plugins.md new file mode 100644 index 0000000000..f66a9b9c51 --- /dev/null +++ b/content/influxdb/v2.1/reference/telegraf-plugins.md @@ -0,0 +1,12 @@ +--- +title: Telegraf plugins +description: > + Telegraf is a plugin-driven agent that collects, processes, aggregates, and writes metrics. + It supports four categories of plugins including input, output, aggregator, and processor. + View and search all available Telegraf plugins. +--- + +Telegraf is a plugin-driven agent that collects, processes, aggregates, and writes metrics. +It supports four categories of plugins including input, output, aggregator, and processor. + +}}/plugins//">View Telegraf plugins diff --git a/content/influxdb/v2.1/reference/urls.md b/content/influxdb/v2.1/reference/urls.md new file mode 100644 index 0000000000..679c89179b --- /dev/null +++ b/content/influxdb/v2.1/reference/urls.md @@ -0,0 +1,45 @@ +--- +title: InfluxDB OSS URLs +description: > + InfluxDB OSS is accessed at `localhost:8086` by default, but you can also + customize your InfluxDB host and port. +weight: 6 +menu: + influxdb_2_1_ref: + name: InfluxDB URLs +--- + +InfluxDB OSS is accessed at `localhost:8086` by default, but you can also +customize your InfluxDB host and port. + +**Default host:** `localhost` +**Default port:** `8086` + +{{< keep-url >}} +``` +http://localhost:8086/ +``` + +## Customize your InfluxDB OSS URL +To customize your InfluxDB host and port, use the +[`http-bind-address` configuration option](/influxdb/v2.1/reference/config-options/#http-bind-address) +when starting `influxd`. + +{{< keep-url >}} +```sh +# Syntax +influxd --http-bind-address : + +# Example - Run InfluxDB at http://example.com:8080 +influxd --http-bind-address example.com:8080 + +# Example - Run InfluxDB at http://localhost:8080 +influxd --http-bind-address :8080 +``` + +{{% note %}} +#### Configure DNS routing +You must configure DNS routing to successfully route requests to your custom hostname. +Methods for configuring DNS routing vary depending on your operating system and +network architecture and are not covered in this documentation. +{{% /note %}} diff --git a/content/influxdb/v2.1/security/_index.md b/content/influxdb/v2.1/security/_index.md new file mode 100644 index 0000000000..1e88d52738 --- /dev/null +++ b/content/influxdb/v2.1/security/_index.md @@ -0,0 +1,25 @@ +--- +title: Manage security and authorization +description: > + Security, access control, and sensitive secret handling are incredibly important + when handling any sort of sensitive data. + This section provides information about managing the security of your InfluxDB instance. +weight: 12 +menu: + influxdb_2_1: + name: Security & authorization +influxdb/v2.1/tags: [security, authentication] +--- + +Security, access control, and sensitive secret handling are incredibly important +when handling any sort of sensitive data. +This section provides information about managing the security of your InfluxDB instance. + +{{% note %}} +#### InfluxDB 2.x/1.x compatibility +If you [upgraded from 1.x to {{< current-version >}}](/influxdb/v2.1/upgrade/v1-to-v2/), +use the [`influx v1 auth`](/influxdb/v2.1/reference/cli/influx/v1/auth/) commands +to manage authorizations for the [1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). +{{% /note %}} + +{{< children >}} diff --git a/content/influxdb/v2.1/security/enable-tls.md b/content/influxdb/v2.1/security/enable-tls.md new file mode 100644 index 0000000000..3c26baacf1 --- /dev/null +++ b/content/influxdb/v2.1/security/enable-tls.md @@ -0,0 +1,154 @@ +--- +title: Enable TLS encryption +seotitle: Enable TLS/SSL encryption +description: > + Enable Transport Layer Security (TLS) and use the HTTPS protocol to secure communication between clients and InfluxDB. +weight: 101 +menu: + influxdb_2_1: + parent: Security & authorization +influxdb/v2.1/tags: [security, authentication, tls, https, ssl] +products: [oss] +--- + +Enabling TLS encrypts the communication between clients and the InfluxDB server. +When configured with a signed certificate, TLS also allows clients to verify the authenticity of the InfluxDB server. + +To set up TLS over HTTPS, do the following: + +- [Obtain requirements](#obtain-requirements) +- [Configure InfluxDB to use TLS](#configure-influxdb-to-use-tls) + +{{% warn %}} +InfluxData **strongly recommends** enabling HTTPS, especially if you plan on sending requests to InfluxDB over a network. +{{% /warn %}} + +## Obtain requirements + +To enable HTTPS with InfluxDB, you need a Transport Layer Security (TLS) certificate, also known as a Secured Sockets Layer (SSL) certificate. +InfluxDB supports three types of TLS certificates: + +* **Single domain certificates signed by a [Certificate Authority](https://en.wikipedia.org/wiki/Certificate_authority)** + + Single domain certificates provide cryptographic security to HTTPS requests and allow clients to verify the identity of the InfluxDB server. + These certificates are signed and issued by a trusted, third-party Certificate Authority (CA). + With this certificate option, every InfluxDB instance requires a unique single domain certificate. + +* **Wildcard certificates signed by a Certificate Authority** + + Wildcard certificates provide cryptographic security to HTTPS requests and allow clients to verify the identity of the InfluxDB server. + Wildcard certificates can be used across multiple InfluxDB instances on different servers. + +* **Self-signed certificates** + + Self-signed certificates are _not_ signed by a trusted, third-party CA. + Unlike CA-signed certificates, self-signed certificates only provide cryptographic security to HTTPS requests. + They do not allow clients to verify the identity of the InfluxDB server. + With this certificate option, every InfluxDB instance requires a unique self-signed certificate. + You can generate a self-signed certificate on your own machine. + + + + +## Configure InfluxDB to use TLS + +1. **Download or generate certificate files** + + If using a certificate provided by a CA, follow their instructions to download the certificate files. + + If using a self-signed certificate, use the `openssl` utility to create a certificate. + + The following command generates a private key file (.key) and a self-signed certificate file (.crt) with required permissions + and saves them to `/etc/ssl/`. + (Other paths will also work.) + Files remain valid for the specified `NUMBER_OF_DAYS`. + + ```sh + sudo openssl req -x509 -nodes -newkey rsa:2048 \ + -keyout /etc/ssl/influxdb-selfsigned.key \ + -out /etc/ssl/influxdb-selfsigned.crt \ + -days + ``` + + The command will prompt you for more information. + You can choose to fill out these fields or leave them blank; both actions generate valid certificate files. + +2. **Set certificate file permissions** + + The user running InfluxDB must have read permissions on the TLS certificate. + + {{% note %}}You may opt to set up multiple users, groups, and permissions. + Ultimately, make sure all users running InfluxDB have read permissions for the TLS certificate. + {{% /note %}} + + Run the following command to give InfluxDB read and write permissions on the certificate files. + + ```bash + sudo chmod 644 /etc/ssl/ + sudo chmod 600 /etc/ssl/ + ``` + +3. **Run `influxd` with TLS flags** + + Start InfluxDB with TLS command line flags: + + ```bash + influxd \ + --tls-cert="" \ + --tls-key="" + ``` + +4. **Verify TLS connection** + + + Ensure you can connect over HTTPS by running + + ``` + curl -v https://localhost:8086/api/v2/ping + ``` + + If using a self-signed certificate, use the `-k` flag to skip certificate verification: + + ``` + curl -vk https://localhost:8086/api/v2/ping + ``` + + With this command, you should see output confirming a succussful TLS handshake. + +You can further configure TLS settings using +[`tls-min-version`](/influxdb/v2.1/reference/config-options/#tls-min-version) +and +[`tls-strict-ciphers`](/influxdb/v2.1/reference/config-options/#tls-strict-ciphers). + +## Connect Telegraf to a secured InfluxDB instance + +To connect [Telegraf](/{{< latest "telegraf" >}}/) to an InfluxDB {{< current-version >}} instance with TLS enabled, +update the following `influxdb_v2` output settings in your Telegraf configuration file: + +- Update URLs to use HTTPS instead of HTTP. +- If using a self-signed certificate, uncomment and set `insecure_skip_verify` to `true`. + +### Example configuration + +```toml +############################################################################### +# OUTPUT PLUGINS # +############################################################################### + +# Configuration for sending metrics to InfluxDB +[[outputs.influxdb_v2]] + ## The URLs of the InfluxDB cluster nodes. + ## + ## Multiple URLs can be specified for a single cluster, only ONE of the + ## urls will be written to each interval. + urls = ["https://127.0.0.1:8086"] + + [...] + + ## Optional TLS Config for use on HTTP connections. + [...] + ## Use TLS but skip chain & host verification + insecure_skip_verify = true +``` + +Restart Telegraf using the updated configuration file. diff --git a/content/influxdb/v2.1/security/secrets/_index.md b/content/influxdb/v2.1/security/secrets/_index.md new file mode 100644 index 0000000000..d903366be2 --- /dev/null +++ b/content/influxdb/v2.1/security/secrets/_index.md @@ -0,0 +1,24 @@ +--- +title: Manage secrets +description: Manage, use, and store secrets in InfluxDB. +influxdb/v2.1/tags: [secrets, security] +menu: + influxdb_2_1: + parent: Security & authorization +weight: 102 +aliases: + - /influxdb/v2.1/security/secrets/manage-secrets/ +--- + +Secrets are key-value pairs that contain sensitive information you want to control +access to, such as API keys, passwords, or certificates. +There are two options for storing secrets with InfluxDB: + +- By default, secrets are Base64-encoded and stored in the InfluxDB embedded key value store, + [BoltDB](https://github.com/boltdb/bolt). +- You can also set up a Vault server to store secrets. + For details, see [Store secrets in Vault](/influxdb/v2.1/security/secrets/use-vault). + +--- + +{{< children >}} diff --git a/content/influxdb/v2.1/security/secrets/add.md b/content/influxdb/v2.1/security/secrets/add.md new file mode 100644 index 0000000000..0d4e7b4511 --- /dev/null +++ b/content/influxdb/v2.1/security/secrets/add.md @@ -0,0 +1,58 @@ +--- +title: Add secrets +description: Add secrets using the `influx` CLI or the InfluxDB API. +influxdb/v2.1/tags: [secrets, security] +menu: + influxdb_2_1: + parent: Manage secrets +weight: 301 +aliases: + - /influxdb/v2.1/security/secrets/manage-secrets/add/ +--- + +Add secrets using the `influx` command line interface (CLI) or the InfluxDB API. + + +- [Add a secret using the influx CLI](#add-a-secret-using-the-influx-cli) +- [Add a secret using the InfluxDB API](#add-a-secret-using-the-influxdb-api) + +## Add a secret using the influx CLI +Use the [`influx secret update` command](/influxdb/v2.1/reference/cli/influx/secret/update/) +to add a new secret to your organization. +Provide the secret key with the `-k` or `--key` flag. +You may also provide the secret value with the `-v` or `--value` flag. +If you do not provide the secret value with the `-v` or `--value` flag, +enter the value when prompted. + +{{% warn %}} +Providing a secret value with the `-v` or `--value` flag may expose the secret +in your command history. +{{% /warn %}} + +```sh +# Syntax +influx secret update -k + +# Example +influx secret update -k foo +``` + +## Add a secret using the InfluxDB API +Use the `PATCH` request method and the `/orgs/{orgID}/secrets` API endpoint to +add a new secret to your organization. + +**Include the following:** + +- Your [organization ID](/influxdb/v2.1/organizations/view-orgs/#view-your-organization-id) in the request URL +- Your [API token](/influxdb/v2.1/security/tokens/view-tokens/) in the `Authorization` header +- The secret key-value pair in the request body + + +```sh +curl --request PATCH http://localhost:8086/api/v2/orgs//secrets \ + --header 'Authorization: Token YOURAUTHTOKEN' \ + --header 'Content-type: application/json' \ + --data '{ + "": "" +}' +``` diff --git a/content/influxdb/v2.1/security/secrets/delete.md b/content/influxdb/v2.1/security/secrets/delete.md new file mode 100644 index 0000000000..0268af1fb7 --- /dev/null +++ b/content/influxdb/v2.1/security/secrets/delete.md @@ -0,0 +1,50 @@ +--- +title: Delete secrets +description: Delete secrets using the `influx` CLI or the InfluxDB API. +influxdb/v2.1/tags: [secrets, security] +menu: + influxdb_2_1: + parent: Manage secrets +weight: 304 +aliases: + - /influxdb/v2.1/security/secrets/manage-secrets/delete/ +--- + +Delete secrets using the `influx` command line interface (CLI) or the InfluxDB API. + +- [Delete a secret using the influx CLI](#delete-a-secret-using-the-influx-cli) +- [Delete secrets using the InfluxDB API](#delete-secrets-using-the-influxdb-api) + +## Delete a secret using the influx CLI +Use the [`influx secret delete` command](/influxdb/v2.1/reference/cli/influx/secret/delete/) +to delete a secret key-value pair from your organization. +Provide the secret key to delete with the `-k` or `--key` flag. + +```sh +# Syntax +influx secret delete -k + +# Example +influx secret delete -k foo +``` + +## Delete secrets using the InfluxDB API +Use the `POST` request method and the `orgs/{orgID}/secrets/delete` API endpoint +to delete one or more secrets. + +**Include the following:** + +- Your [organization ID](/influxdb/v2.1/organizations/view-orgs/#view-your-organization-id) in the request URL +- Your [API token](/influxdb/v2.1/security/tokens/view-tokens/) in the `Authorization` header +- An array of secret keys to delete in the request body + + +```bash +curl --request GET http://localhost:8086/api/v2/orgs//secrets/delete \ + --header 'Authorization: Token YOURAUTHTOKEN' \ + --data '{ + "secrets": [ + "" + ] +}' +``` diff --git a/content/influxdb/v2.1/security/secrets/update.md b/content/influxdb/v2.1/security/secrets/update.md new file mode 100644 index 0000000000..a3248ebde2 --- /dev/null +++ b/content/influxdb/v2.1/security/secrets/update.md @@ -0,0 +1,57 @@ +--- +title: Update secrets +description: Update secrets using the `influx` CLI or the InfluxDB API. +influxdb/v2.1/tags: [secrets, security] +menu: + influxdb_2_1: + parent: Manage secrets +weight: 303 +aliases: + - /influxdb/v2.1/security/secrets/manage-secrets/update/ +--- + +Update secrets using the `influx` command line interface (CLI) or the InfluxDB API. + +- [Update a secret using the influx CLI](#update-a-secret-using-the-influx-cli) +- [Update a secret using the InfluxDB API](#update-a-secret-using-the-influxdb-api) + +## Update a secret using the influx CLI +Use the [`influx secret update` command](/influxdb/v2.1/reference/cli/influx/secret/update/) +to update a secret in your organization. +Provide the secret key to update with the `-k` or `--key` flag. +You may also provide the secret value with the `-v` or `--value` flag. +If you do not provide the secret value with the `-v` or `--value` flag, +enter the value when prompted. + +{{% warn %}} +Providing a secret value with the `-v` or `--value` flag may expose the secret +in your command history. +{{% /warn %}} + +```sh +# Syntax +influx secret update -k + +# Example +influx secret update -k foo +``` + +## Update a secret using the InfluxDB API +Use the `PATCH` request method and the InfluxDB `/orgs/{orgID}/secrets` API endpoint +to update a secret in your organization. + +**Include the following:** + +- Your [organization ID](/influxdb/v2.1/organizations/view-orgs/#view-your-organization-id) in the request URL +- Your [API token](/influxdb/v2.1/security/tokens/view-tokens/) in the `Authorization` header +- The updated secret key-value pair in the request body + + +```sh +curl --request PATCH http://localhost:8086/api/v2/orgs//secrets \ + --header 'Authorization: Token YOURAUTHTOKEN' \ + --header 'Content-type: application/json' \ + --data '{ + "": "" +}' +``` diff --git a/content/influxdb/v2.1/security/secrets/use-vault.md b/content/influxdb/v2.1/security/secrets/use-vault.md new file mode 100644 index 0000000000..3cb551c9ef --- /dev/null +++ b/content/influxdb/v2.1/security/secrets/use-vault.md @@ -0,0 +1,98 @@ +--- +title: Store secrets in Vault +description: Use Vault as an InfluxDB secret store and manage secrets through the in InfluxDB API. +influxdb/v2.1/tags: [secrets, security] +menu: + influxdb_2_1: + parent: Manage secrets +weight: 306 +--- + +[Vault](https://www.vaultproject.io/) secures, stores, and controls access +to tokens, passwords, certificates, and other sensitive secrets. +Store sensitive secrets in Vault using InfluxDB's built-in Vault integration. + +To store secrets in Vault, complete the following steps: + +1. [Start a Vault server](#start-a-vault-server). +2. [Provide Vault server address and token](#provide-vault-server-address-and-token). +3. [Start InfluxDB](#start-influxdb). +4. [Manage secrets through the InfluxDB API](#manage-secrets-through-the-influxdb-api). + +## Start a Vault server + +Start a Vault server and ensure InfluxDB has network access to the server. + +The following links provide information about running Vault in both development and production: + +- [Install Vault](https://learn.hashicorp.com/vault/getting-started/install) +- [Start a Vault dev server](https://learn.hashicorp.com/vault/getting-started/dev-server) +- [Deploy Vault](https://learn.hashicorp.com/vault/getting-started/deploy) + +{{% note %}} +InfluxDB supports the [Vault KV Secrets Engine Version 2 API](https://www.vaultproject.io/api/secret/kv/kv-v2.html) only. +When you create a secrets engine, enable the `kv-v2` version by running: + +```js +vault secrets enable kv-v2 +``` +{{% /note %}} + +For this example, install Vault on your local machine and start a Vault dev server. + +```sh +vault server -dev +``` + +## Provide Vault server address and token + +Use `influxd` Vault-related tags or [Vault environment variables](https://www.vaultproject.io/docs/commands/index.html#environment-variables) +to provide connection credentials and other important Vault-related information to InfluxDB. + +### Required credentials + +#### Vault address + +Provide the API address of your Vault server _(available in the Vault server output)_ +using the [`--vault-addr` flag](/influxdb/v2.1/reference/config-options/#vault-addr) when +starting `influxd` or with the `VAULT_ADDR` environment variable. + +#### Vault token + +Provide your [Vault token](https://learn.hashicorp.com/vault/getting-started/authentication) +(required to access your Vault server) using the [`--vault-token` flag](/influxdb/v2.1/reference/config-options/#vault-token) +when starting `influxd` or with the `VAULT_TOKEN` environment variable. + +_Your Vault server configuration may require other Vault settings._ + +## Start InfluxDB + +Start the [`influxd` service](/influxdb/v2.1/reference/cli/influxd/) with the `--secret-store` +option set to `vault` any other necessary flags. + +```bash +influxd --secret-store vault \ + --vault-addr=http://127.0.0.1:8200 \ + --vault-token=s.0X0XxXXx0xXxXXxxxXxXxX0x +``` + +`influxd` includes the following Vault configuration options. +If set, these flags override any [Vault environment variables](https://www.vaultproject.io/docs/commands/index.html#environment-variables): + +- `--vault-addr` +- `--vault-cacert` +- `--vault-capath` +- `--vault-client-cert` +- `--vault-client-key` +- `--vault-max-retries` +- `--vault-client-timeout` +- `--vault-skip-verify` +- `--vault-tls-server-name` +- `--vault-token` + +For more information, see [InfluxDB configuration options](/influxdb/v2.1/reference/config-options/). + +## Manage secrets through the InfluxDB API + +Use the InfluxDB `/org/{orgID}/secrets` API endpoint to add tokens to Vault. +For details, see [Manage secrets](/influxdb/v2.1/security/secrets/manage-secrets/). diff --git a/content/influxdb/v2.1/security/secrets/use.md b/content/influxdb/v2.1/security/secrets/use.md new file mode 100644 index 0000000000..6dae06b7d3 --- /dev/null +++ b/content/influxdb/v2.1/security/secrets/use.md @@ -0,0 +1,29 @@ +--- +title: Use secrets +description: Use secrets in a query with Flux. +influxdb/v2.1/tags: [secrets, security] +menu: + influxdb_2_1: + parent: Manage secrets +weight: 305 +aliases: + - /influxdb/v2.1/security/secrets/manage-secrets/use/ +--- + +## Use secrets in a query +Import the `influxdata/influxd/secrets` package and use the `secrets.get()` function +to populate sensitive data in queries with secrets from your secret store. + +```js +import "influxdata/influxdb/secrets" +import "sql" + +username = secrets.get(key: "POSTGRES_USERNAME") +password = secrets.get(key: "POSTGRES_PASSWORD") + +sql.from( + driverName: "postgres", + dataSourceName: "postgresql://${username}:${password}@localhost", + query:"SELECT * FROM example-table" +) +``` diff --git a/content/influxdb/v2.1/security/secrets/view.md b/content/influxdb/v2.1/security/secrets/view.md new file mode 100644 index 0000000000..8c57c42053 --- /dev/null +++ b/content/influxdb/v2.1/security/secrets/view.md @@ -0,0 +1,39 @@ +--- +title: View secret keys +description: View secret keys using the `influx` CLI or the InfluxDB API. +influxdb/v2.1/tags: [secrets, security] +menu: + influxdb_2_1: + parent: Manage secrets +weight: 302 +aliases: + - /influxdb/v2.1/security/secrets/manage-secrets/view/ +--- + +View secret keys using the `influx` command line interface (CLI) or the InfluxDB API. + +- [View secret keys using the influx CLI](#view-secret-keys-using-the-influx-cli) +- [View secret keys using the InfluxDB API](#view-secret-keys-using-the-influxdb-api) + +## View secret keys using the influx CLI +Use the [`influx secret list` command](/influxdb/v2.1/reference/cli/influx/secret/list/) +to list your organization's secret keys. + +```sh +influx secret list +``` + +## View secret keys using the InfluxDB API +Use the `GET` request method and the InfluxDB `/orgs/{orgID}/secrets` API endpoint +to view your organization's secrets keys. + +**Include the following:** + +- Your [organization ID](/influxdb/v2.1/organizations/view-orgs/#view-your-organization-id) in the request URL +- Your [API token](/influxdb/v2.1/security/tokens/view-tokens/) in the `Authorization` header + + +```sh +curl --request GET http://localhost:8086/api/v2/orgs//secrets \ + --header 'Authorization: Token YOURAUTHTOKEN' +``` diff --git a/content/influxdb/v2.1/security/tokens/_index.md b/content/influxdb/v2.1/security/tokens/_index.md new file mode 100644 index 0000000000..1cc773afae --- /dev/null +++ b/content/influxdb/v2.1/security/tokens/_index.md @@ -0,0 +1,43 @@ +--- +title: Manage API tokens +seotitle: Manage API tokens in InfluxDB +description: Manage API tokens in InfluxDB using the InfluxDB UI or the influx CLI. +aliases: + - /influxdb/v2.1/users/tokens +influxdb/v2.1/tags: [tokens, authentication, security] +menu: + influxdb_2_1: + name: Manage tokens + parent: Security & authorization +weight: 103 +--- + +InfluxDB **API tokens** ensure secure interaction between InfluxDB and external tools such as clients or applications. +An API token belongs to a specific user and identifies InfluxDB permissions within the user's organization. + +Learn how to create, view, update, or delete an API token. + +## API token types + +- [Operator API token](#operator-token) +- [All-Access API token](#all-access-token) +- [Read/Write token](#readwrite-token) + +#### Operator token +Grants full read and write access to all resources in **all organizations in InfluxDB OSS 2.x**. + +{{% note %}} +Operator tokens are created in the InfluxDB setup process and cannot be created manually. +Because Operator tokens have full read and write access to all organizations in the database, +we recommend [creating an All-Access token](/influxdb/v2.1/security/tokens/create-token/) +for each organization and using those to manage InfluxDB. +This helps to prevent accidental interactions across organizations. +{{% /note %}} + +#### All-Access token +Grants full read and write access to all resources in an organization. + +#### Read/Write token +Grants read access, write access, or both to specific buckets in an organization. + +{{< children hlevel="h2" >}} diff --git a/content/influxdb/v2.1/security/tokens/create-token.md b/content/influxdb/v2.1/security/tokens/create-token.md new file mode 100644 index 0000000000..95779fce02 --- /dev/null +++ b/content/influxdb/v2.1/security/tokens/create-token.md @@ -0,0 +1,115 @@ +--- +title: Create a token +seotitle: Create an API token in InfluxDB +description: Create an API token in InfluxDB using the InfluxDB UI, the `influx` CLI, or the InfluxDB API. +aliases: + - /influxdb/v2.1/users/tokens/create-token/ +menu: + influxdb_2_1: + name: Create a token + parent: Manage tokens +weight: 201 +--- + +Create API tokens using the InfluxDB user interface (UI), the `influx` +command line interface (CLI), or the InfluxDB API. + +{{% note %}} +Tokens are visible to the user who created the token. +{{% oss-only %}}Users who own a token with Operator permissions also have access to all tokens.{{% /oss-only %}} +Tokens stop working when the user who created the token is deleted. +**We recommend creating a generic user to create and manage tokens for writing data.** +{{% /note %}} + +## Create a token in the InfluxDB UI + +1. In the navigation menu on the left, select **Data (Load Data)** > **Tokens**. + + {{< nav-icon "disks" >}} + +2. Click **{{< icon "plus" >}} Generate** and select a token type + (**Read/Write Token** or **All-Access Token**). +3. In the window that appears, enter a description for your token in the **Description** field. +4. If generating a **read/write token**: + - Search for and select buckets to read from in the **Read** pane. + - Search for and select buckets to write to in the **Write** pane. +5. Click **Save**. + +## Create a token using the influx CLI + +Use the [`influx auth create` command](/influxdb/v2.1/reference/cli/influx/auth/create) to create a token. +Include flags with the command to grant specific permissions to the token. +See the [available flags](/influxdb/v2.1/reference/cli/influx/auth/create#flags). +Only tokens with the `write: authorizations` permission can create tokens. + +```sh +# Syntax +influx auth create -o [permission-flags] +``` + +### Examples +#### Create an All-Access token + +Create an All-Access token to grant permissions to all resources in an organization. + +```sh +influx auth create \ + --org my-org \ + --all-access +``` + +#### Create an Operator token + +Create an Operator token to grant permissions to all resources in all organizations. + +```sh +influx auth create \ + --org my-org \ + --operator +``` + +#### Create a token with specified read permissions + +```sh +influx auth create \ + --org my-org \ + --read-bucket 03a2bbf46309a000 \ + --read-bucket 3a87c03ace269000 \ + --read-dashboards \ + --read-tasks \ + --read-telegrafs \ + --read-user +``` + +See the [`influx auth create` documentation](/influxdb/{{< latest "influxdb" >}}/reference/cli/influx/auth/create) for information about other available flags. + +## Create a token using the InfluxDB API + +Use the `/authorizations` endpoint of the InfluxDB API to create a token. + +{{% api-endpoint method="POST" endpoint="http://localhost:8086/api/v2/authorizations" %}} + +Include the following in your request: + +| Requirement | Include by | +|:----------- |:---------- | +| API token with the [`write: authorizations`](/influxdb/v2.1/api/#operation/PostAuthorizations) permission | Use the `Authorization` header and the {{% oss-only %}}`Bearer` or {{% /oss-only %}}`Token` scheme. | +| Organization | Pass as `orgID` in the request body. +| Permissions list | Pass as a `permissions` array in the request body. + +```sh +{{% get-shared-text "api/v2.0/auth/oss/token-create.sh" %}} +``` + +### Create a token scoped to a user + +To scope a token to a user other than the token creator, pass `userID` in the request +body. + +```sh +{{% get-shared-text "api/v2.0/auth/oss/tokens-create-with-user.sh" %}} +``` + +See the +[`POST /api/v2/authorizations` documentation](/influxdb/v2.1/api/#operation/PostAuthorizations) +for more information about options. diff --git a/content/influxdb/v2.1/security/tokens/delete-token.md b/content/influxdb/v2.1/security/tokens/delete-token.md new file mode 100644 index 0000000000..6465efc423 --- /dev/null +++ b/content/influxdb/v2.1/security/tokens/delete-token.md @@ -0,0 +1,39 @@ +--- +title: Delete a token +seotitle: Delete an API token from InfluxDB +description: Delete an API token from InfluxDB using the InfluxDB UI or the `influx` CLI. +aliases: + - /influxdb/v2.1/users/tokens/delete-token +menu: + influxdb_2_1: + name: Delete a token + parent: Manage tokens +weight: 204 +--- + +Delete API tokens from the InfluxDB user interface (UI) or the `influx` command line interface (CLI). +Once deleted, all users and external integrations using the API token will no longer +have access to your InfluxDB instance. + +## Delete tokens in the InfluxDB UI + +1. In the navigation menu on the left, select **Data (Load Data)** > **Tokens**. + + {{< nav-icon "disks" >}} + +2. Hover over the token you want to delete and click **Delete** and **Confirm**. + +## Delete tokens using the influx CLI + +Use the [`influx auth delete` command](/influxdb/v2.1/reference/cli/influx/auth/delete) +to delete a token. + +_This command requires an auth ID, which is available in the output of `influx auth find`._ + +```sh +# Syntax +influx auth delete -i + +# Example +influx auth delete -i 03a2bee5a9c9a000 +``` diff --git a/content/influxdb/v2.1/security/tokens/update-tokens.md b/content/influxdb/v2.1/security/tokens/update-tokens.md new file mode 100644 index 0000000000..52d9e05a2c --- /dev/null +++ b/content/influxdb/v2.1/security/tokens/update-tokens.md @@ -0,0 +1,31 @@ +--- +title: Update a token +seotitle: Update API tokens in InfluxDB +description: Update API tokens' descriptions in InfluxDB using the InfluxDB UI. +aliases: + - /influxdb/v2.1/users/tokens/update-tokens +menu: + influxdb_2_1: + name: Update a token + parent: Manage tokens +weight: 203 +--- + +Update an API token's description using the InfluxDB user interface (UI). + +## Update a token in the InfluxDB UI + +1. In the navigation menu on the left, select **Data (Load Data)** > **Tokens**. + + {{< nav-icon "disks" >}} + +2. Click the pencil icon {{< icon "pencil" >}} next to the token's name in the **Description** column. +3. Update the token description, then click anywhere else to save. + +## Enable or disable a token + +1. In the navigation menu on the left, select **Data (Load Data)** > **Tokens**. + + {{< nav-icon "disks" >}} + +2. Click the **{{< icon "toggle-green" >}} Status** toggle. diff --git a/content/influxdb/v2.1/security/tokens/use-tokens.md b/content/influxdb/v2.1/security/tokens/use-tokens.md new file mode 100644 index 0000000000..6b97a39fc4 --- /dev/null +++ b/content/influxdb/v2.1/security/tokens/use-tokens.md @@ -0,0 +1,44 @@ +--- +title: Use tokens +seotitle: Use an API token in InfluxDB +description: Use an API token in the InfluxDB UI, the `influx` CLI, or the InfluxDB API. +aliases: + - /influxdb/v2.1/users/tokens/use-tokens +menu: + influxdb_2_1: + name: Use tokens + parent: Manage tokens +weight: 204 +--- + +Use tokens to authenticate requests to InfluxDB, including requests to write, query, and manage data and resources. +Authenticate requests using the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/), API requests made with client libraries, and tools like `curl`. + +### Add a token to a CLI request + +```sh +influx write -t -b BUCKET -o org-name +``` + +``` +export INFLUX_TOKEN=my-token +influx write -t $INFLUX_TOKEN -b my-bucket -o my-org "measurement field=1" +``` + +{{% note %}} +See [here](/influxdb/v2.1/write-data/no-code/use-telegraf/auto-config/#configure-your-token-as-an-environment-variable) +to configure environment variables on Windows. +(Click on the **Windows** tab.) +{{% /note %}} + +### Use CLI configurations + +Automatically manage and use tokens from the CLI using [`influx config`](/influxdb/v2.1/reference/cli/influx/config/). + +### Use a token in an API request + +Use tokens in [API requests](/influxdb/v2.1/api-guide/api_intro/#authentication). + +### Use a token in Postman + +Make authenticated requests with tokens [using Postman](/influxdb/v2.1/api-guide/postman/). diff --git a/content/influxdb/v2.1/security/tokens/view-tokens.md b/content/influxdb/v2.1/security/tokens/view-tokens.md new file mode 100644 index 0000000000..c4d15bcffc --- /dev/null +++ b/content/influxdb/v2.1/security/tokens/view-tokens.md @@ -0,0 +1,77 @@ +--- +title: View tokens +seotitle: View API tokens in InfluxDB +description: View API tokens in InfluxDB using the InfluxDB UI, the `influx` CLI, or the InfluxDB API. +aliases: + - /influxdb/v2.1/users/tokens/view-tokens +menu: + influxdb_2_1: + name: View tokens + parent: Manage tokens +weight: 202 +--- + +View API tokens and permissions using the InfluxDB user interface (UI), +the `influx` command line interface (CLI), or the InfluxDB API. + +{{% note %}} +Tokens are visible only to the user who created them and stop working when the user is deactivated. +We recommend creating a generic IT user to create and manage tokens for writing data. +{{% /note %}} + +## View tokens in the InfluxDB UI + +1. In the navigation menu on the left, select **Data (Load Data)** > **Tokens**. + + {{< nav-icon "disks" >}} + +2. Click a token name from the list to view the token and a summary of access permissions. + +## View tokens using the influx CLI + +Use the [`influx auth list` command](/influxdb/v2.1/reference/cli/influx/auth/list) +to view tokens. + +```sh +influx auth list +``` + +Filtering options such as filtering by authorization ID, username, or user ID are available. +See the [`influx auth list` documentation](/influxdb/v2.1/reference/cli/influx/auth/list) +for information about other available flags. + +## View tokens using the InfluxDB API + +Use the `/authorizations` endpoint of the InfluxDB API to view tokens and permissions. + +{{% api-endpoint method="GET" endpoint="/api/v2/authorizations" %}} + +Include the following in your request: + +| Requirement | Include by | +|:----------- |:---------- | +| API token with the [`read: authorizations`](/influxdb/v2.1/api/#operation/PostAuthorizations) permission | Use the `Authorization: Token YOUR_API_TOKEN` header. | + +```sh +{{% get-shared-text "api/v2.0/auth/oss/tokens-view.sh" %}} +``` + +### View a single token + +To view a specific authorization and token, include the authorization ID in the URL path. + +{{% api-endpoint method="GET" endpoint="/api/v2/authorizations/{authID}" %}} + +### Filter the token list + +InfluxDB returns authorizations from the same organization as the token used in the request. +To filter tokens by user, include `userID` as a query parameter in your request. + +```sh +{{% get-shared-text "api/v2.0/auth/oss/tokens-view-filter.sh" %}} +``` + +[***Operator tokens***](/{{% latest "influxdb" %}}/security/tokens/#operator-token) have access to all organizations' authorizations. +To filter authorizations by organization when using an operator token, include an `org` or `orgID` query parameter in your request. + +See the [`/authorizations` endpoint documentation](/influxdb/v2.1/api/#tag/Authorizations) for more information about available parameters. diff --git a/content/influxdb/v2.1/tags/_index.md b/content/influxdb/v2.1/tags/_index.md new file mode 100644 index 0000000000..3a3d5c8281 --- /dev/null +++ b/content/influxdb/v2.1/tags/_index.md @@ -0,0 +1,4 @@ +--- +title: Tags and related content +layout: tags-landing +--- diff --git a/content/influxdb/v2.1/telegraf-configs/_index.md b/content/influxdb/v2.1/telegraf-configs/_index.md new file mode 100644 index 0000000000..06e0e32e0c --- /dev/null +++ b/content/influxdb/v2.1/telegraf-configs/_index.md @@ -0,0 +1,37 @@ +--- +title: Telegraf configurations +description: > + InfluxDB OSS lets you automatically generate Telegraf configurations or upload custom + Telegraf configurations that collect metrics and write them to InfluxDB OSS. +weight: 12 +menu: influxdb_2_1 +influxdb/v2.1/tags: [telegraf] +related: + - /influxdb/v2.1/write-data/no-code/use-telegraf/manual-config/ + - /influxdb/v2.1/write-data/no-code/use-telegraf/auto-config/ +--- + +InfluxDB lets you automatically generate Telegraf configurations or upload custom +Telegraf configurations that collect metrics and write them to InfluxDB. +Telegraf retrieves configurations from InfluxDB on startup. + +## Use InfluxDB Telegraf configurations +With a Telegraf configuration stored in InfluxDB, the `telegraf` agent can retrieve +the configuration from an InfluxDB HTTP(S) endpoint. + +- Ensure Telegraf has network access to InfluxDB (OSS or Cloud). +- Start the `telegraf` agent using the `--config` flag to provide the URL of the + InfluxDB Telegraf configuration. For example: + + ```sh + telegraf --config http://localhost:8086/api/v2/telegrafs/ + ``` + +{{% note %}} +_[Setup instructions](/influxdb/v2.1/telegraf-configs/view/#view-setup-instructions) for +each Telegraf configuration are provided in the InfluxDB UI._ +{{% /note %}} + +## Manage Telegraf configurations + +{{< children >}} diff --git a/content/influxdb/v2.1/telegraf-configs/clone.md b/content/influxdb/v2.1/telegraf-configs/clone.md new file mode 100644 index 0000000000..061c4a9f7d --- /dev/null +++ b/content/influxdb/v2.1/telegraf-configs/clone.md @@ -0,0 +1,21 @@ +--- +title: Clone a Telegraf configuration +description: > + Use the InfluxDB UI to clone an Telegraf configuration. +weight: 101 +menu: + influxdb_2_1: + name: Clone a config + parent: Telegraf configurations +--- + +Use the InfluxDB user interface (UI) to clone a Telegraf configuration. + + +1. In the navigation menu on the left, select **Data** (**Load Data**) > **Telegraf**. + + {{< nav-icon "load data" >}} + +2. Hover over the configuration you want to clone, click the **{{< icon "clone" >}}** + icon, and then click **Clone**. + The clone appears in your list of Telegraf configurations. diff --git a/content/influxdb/v2.1/telegraf-configs/create.md b/content/influxdb/v2.1/telegraf-configs/create.md new file mode 100644 index 0000000000..eadba8c12c --- /dev/null +++ b/content/influxdb/v2.1/telegraf-configs/create.md @@ -0,0 +1,72 @@ +--- +title: Create a Telegraf configuration +description: > + Use the InfluxDB UI or the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) + to create an Telegraf configuration. +weight: 101 +menu: + influxdb_2_1: + name: Create a config + parent: Telegraf configurations +related: + - /influxdb/v2.1/write-data/no-code/use-telegraf/manual-config/ + - /influxdb/v2.1/write-data/no-code/use-telegraf/auto-config/ + - /influxdb/v2.1/telegraf-configs/update/ +--- +Telegraf has an extensive list of plugins for many different technologies and use cases. +Not all plugins are available through the InfluxDB UI, but you can +[create and upload custom Telegraf configurations](#create-a-custom-telegraf-configuration) +to include any of the available [Telegraf plugins](/{{< latest "telegraf" >}}/plugins/). + +Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) +to create a Telegraf configuration. + +To create a Telegraf configuration, do one of the following: + +- [Use the InfluxDB UI](#use-the-influxdb-ui) +- [Use the `influx` CLI](#use-the-influx-cli) +- [Create a custom Telegraf configuration](#create-a-custom-telegraf-configuration) + +## Use the InfluxDB UI +Use the InfluxDB UI to automatically generate and store new Telegraf configurations in InfluxDB. +Creating the configuration in the UI lets you select from a list of available technologies and generates a Telegraf configuration to collect metrics from those technologies. +For more information, see [Automatically configure Telegraf](/influxdb/v2.1/write-data/no-code/use-telegraf/auto-config/). + +## Use the influx CLI +Use the [`influx telegrafs create` command](/influxdb/v2.1/reference/cli/influx/telegrafs/create/) +to upload a Telegraf configuration file from your local machine and create a new Telegraf +configuration in InfluxDB. + +Provide the following: + +- **Telegraf configuration name** +- **Telegraf configuration description** +- **Telegraf configuration file** + +{{% note %}} +If a **name** and **description** are not provided, they are set to empty strings. +{{% /note %}} + + +```sh +# Syntax +influx telegrafs create \ + -n \ + -d \ + -f /path/to/telegraf.conf + +# Example +influx telegrafs create \ + -n "Example Telegraf config" + -d "This is a description for an example Telegraf configuration." + -f /path/to/telegraf.conf +``` + +## Create a custom Telegraf configuration + +1. Create a custom Telegraf configuration file that includes the `outputs.influxdb_v2` + output plugin. _See [Manually configure Telegraf](/influxdb/v2.1/write-data/no-code/use-telegraf/manual-config/)_ + for more information. +2. Add and customize [Telegraf plugins](/{{< latest "telegraf" >}}/plugins/) and save your changes. +3. [Use the `influx telegrafs create` command](#use-the-influx-cli) to upload your + custom Telegraf configuration to InfluxDB. diff --git a/content/influxdb/v2.1/telegraf-configs/remove.md b/content/influxdb/v2.1/telegraf-configs/remove.md new file mode 100644 index 0000000000..d9a6b44aa9 --- /dev/null +++ b/content/influxdb/v2.1/telegraf-configs/remove.md @@ -0,0 +1,53 @@ +--- +title: Remove a Telegraf configuration +description: > + Use the InfluxDB UI or the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) + to remove Telegraf configurations from InfluxDB. +weight: 104 +menu: + influxdb_2_1: + name: Remove a config + parent: Telegraf configurations +aliases: + - /influxdb/v2.1/write-data/no-code/use-telegraf/auto-config/delete-telegraf-config/ + - /influxdb/v2.1/collect-data/use-telegraf/auto-config/delete-telegraf-config +--- + +Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) +to remove Telegraf configurations from InfluxDB. + +{{% note %}} +Deleting a Telegraf configuration does not affect _**running**_ Telegraf agents. +However, if an agents stops, it needs a new configuration to start. +{{% /note %}} + +To remove a Telegraf configuration, do one of the following: + +- [Use the InfluxDB UI](#use-the-influxdb-ui) +- [Use the `influx` CLI](#use-the-influx-cli) + +## Use the InfluxDB UI + +1. In the navigation menu on the left, select **Data** (**Load Data**) > **Telegraf**. + + {{< nav-icon "load data" >}} + +2. Hover over the configuration you want to delete, click the **{{< icon "trash" >}}** + icon, and then click **Delete**. + + +## Use the influx CLI +Use the [`influx telegrafs rm` command](/influxdb/v2.1/reference/cli/influx/telegrafs/rm/) +to remove a Telegraf configuration from InfluxDB. + +Provide the following: + +- **Telegraf configuration ID** (shown in the output of `influx telegrafs`) + +```sh +# Syntax +influx telegrafs rm -i + +# Example +influx telegrafs rm -i 12ab34de56fg78hi +``` diff --git a/content/influxdb/v2.1/telegraf-configs/update.md b/content/influxdb/v2.1/telegraf-configs/update.md new file mode 100644 index 0000000000..da53d3b251 --- /dev/null +++ b/content/influxdb/v2.1/telegraf-configs/update.md @@ -0,0 +1,102 @@ +--- +title: Update a Telegraf configuration +description: > + Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) + to update InfluxDB Telegraf configurations. +weight: 103 +menu: + influxdb_2_1: + name: Update a config + parent: Telegraf configurations +aliases: + - /influxdb/v2.1/write-data/no-code/use-telegraf/auto-config/update-telegraf-config/ + - /influxdb/v2.1/collect-data/use-telegraf/auto-config/update-telegraf-config +--- + +Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) +to update InfluxDB Telegraf configurations. + +To update a Telegraf configuration, do one of the following: + +- [Use the InfluxDB UI](#use-the-influxdb-ui) +- [Use the `influx` CLI](#use-the-influx-cli) + +{{% note %}} +Telegraf doesn't detect changes to remote configurations. If you edit a remote configuration, you must restart Telegraf or send it a SIGHUP command for your changes to take effect. +{{% /note %}} + +## Use the InfluxDB UI + +### Update the name or description of a configuration + +1. In the navigation menu on the left, select **Data** (**Load Data**) > **Telegraf**. + + {{< nav-icon "load data" >}} + +2. Hover over the configuration you want to edit and click **{{< icon "pencil" >}}** + to update the name or description. +3. Press **Return** or click out of the editable field to save your changes. + +### Edit the configuration file directly in the UI + +1. In the navigation menu on the left, select **Data** (**Load Data**) > **Telegraf**. + + {{< nav-icon "load data" >}} + +2. To edit the configuration file: + a. Click the name of the configuration. + b. Add or update [Telegraf plugin settings](/{{< latest "telegraf" >}}/plugins/) in the window that appears. + {{% note %}} + The text editor window doesn't detect if any plugins or settings are misconfigured. Any errors in your configuration that may cause Telegraf to fail when you restart it. + {{% /note %}} + c. Click **Save Changes** and then **Save** again to confirm. +3. To apply the updated configuration, restart Telegraf. To find the exact command to start Telegraf, click **Setup Instructions** on the **Telegraf** page. + +### Download and verify the configuration file + +1. In the navigation menu on the left, select **Data** (**Load Data**) > **Telegraf**. + + {{< nav-icon "load data" >}} + +2. Click the **name** of the Telegraf configuration to customize. +3. Click **Download Config** to download the Telegraf configuration file to your + local machine. +4. Review the configuration file. Add or update [Telegraf plugin](/{{< latest "telegraf" >}}/plugins/) settings and + save your changes. +5. [Use the `influx telegrafs update` command](#use-the-influx-cli) to upload your + modified Telegraf configuration to InfluxDB and replace the existing configuration. +6. To apply the updated configuration, restart Telegraf. To find the exact command to start Telegraf, click **Setup Instructions** on the **Telegraf** page. + +## Use the influx CLI + +Use the [`influx telegrafs update` command](/influxdb/v2.1/reference/cli/influx/telegrafs/update/) +to update an existing InfluxDB Telegraf configuration name, description, or settings +from a Telegraf configuration file on your local machine. + +Provide the following: + +- **Telegraf configuration ID** (shown in the output of `influx telegrafs`) +- **Telegraf configuration name** +- **Telegraf configuration description** +- **Telegraf configuration file** + +{{% warn %}} +If a **name** and **description** are not provided, they are replaced with empty strings. +{{% /warn %}} + + +```sh +# Syntax +influx telegrafs update \ + -i \ + -n \ + -d \ + -f /path/to/telegraf.conf + +# Example +influx telegrafs update \ + -i 12ab34de56fg78hi + -n "Example Telegraf config" + -d "This is a description for an example Telegraf configuration." + -f /path/to/telegraf.conf +``` diff --git a/content/influxdb/v2.1/telegraf-configs/view.md b/content/influxdb/v2.1/telegraf-configs/view.md new file mode 100644 index 0000000000..9f8ee5a48a --- /dev/null +++ b/content/influxdb/v2.1/telegraf-configs/view.md @@ -0,0 +1,45 @@ +--- +title: View Telegraf configurations +description: > + Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) + to view and download InfluxDB Telegraf configurations. +weight: 102 +menu: + influxdb_2_1: + name: View configs + parent: Telegraf configurations +aliases: + - /influxdb/v2.1/write-data/no-code/use-telegraf/auto-config/view-telegraf-config/ + - /influxdb/v2.1/collect-data/use-telegraf/auto-config/view-telegraf-config +--- + +Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) +to view and download InfluxDB Telegraf configurations. + +To view Telegraf configurations, do one of the following: + +- [Use the InfluxDB UI](#use-the-influxdb-ui) +- [Use the `influx` CLI](#use-the-influx-cli) + +## Use the InfluxDB UI +In the navigation menu on the left, select **Data** (**Load Data**) > **Telegraf**. + +{{< nav-icon "load data" >}} + +### View and download the telegraf.conf +To view the `telegraf.conf` associated with the configuration, +click the **Name** of the configuration. +Then click **Download Config** to download the file. + +### View setup instructions +To view the setup instructions for a Telegraf configuration, click **Setup Instructions**. +Setup instructions include commands for adding your InfluxDB API token +as an environment variable and starting Telegraf with the specific configuration. + +## Use the influx CLI +Use the [`influx telegrafs` command](/influxdb/v2.1/reference/cli/influx/telegrafs/) to +list Telegraf configurations stored in InfluxDB. + +```sh +influx telegrafs +``` diff --git a/content/influxdb/v2.1/tools/_index.md b/content/influxdb/v2.1/tools/_index.md new file mode 100644 index 0000000000..e8ef7cbc8b --- /dev/null +++ b/content/influxdb/v2.1/tools/_index.md @@ -0,0 +1,11 @@ +--- +title: InfluxDB tools and integrations +description: > + Use InfluxDB tools and other third-party integrations to interact with, manage, and visualize data in InfluxDB. +weight: 13 +menu: + influxdb_2_1: + name: Tools & integrations +--- + +{{< children >}} diff --git a/content/influxdb/v2.1/tools/chronograf.md b/content/influxdb/v2.1/tools/chronograf.md new file mode 100644 index 0000000000..7d2508b9a8 --- /dev/null +++ b/content/influxdb/v2.1/tools/chronograf.md @@ -0,0 +1,97 @@ +--- +title: Use Chronograf with InfluxDB OSS +description: > + Chronograf is a data visualization and dashboarding tool designed to visualize data in InfluxDB 1.x. + It is part of the [TICKstack](/platform/) that provides an InfluxQL data explorer, Kapacitor integrations, and more. + Continue to use Chronograf with **InfluxDB Cloud** and **InfluxDB OSS 2.x** and the + [1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). +menu: + influxdb_2_1: + name: Use Chronograf + parent: Tools & integrations +weight: 103 +related: + - /{{< latest "chronograf" >}}/ +--- + +[Chronograf](/{{< latest "chronograf" >}}/) is a data visualization and dashboarding +tool designed to visualize data in InfluxDB 1.x. It is part of the [TICKstack](/platform/) +that provides an InfluxQL data explorer, Kapacitor integrations, and more. +Continue to use Chronograf with **InfluxDB Cloud** and **InfluxDB OSS {{< current-version >}}** and the +[1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). + +## Create an InfluxDB connection +1. In Choronograf, click **Configuration** in the left navigation bar, + and then click **{{< icon "plus" >}} Add Connection**. +2. Toggle the **InfluxDB v2 Auth** option at the bottom of the form. + + {{< img-hd src="/img/influxdb/2-0-tools-chronograf-v2-auth.png" alt="InfluxDB v2 Auth toggle" />}} + +3. Enter your InfluxDB connection credentials: + - **Connection URL:** InfluxDB URL _(see [InfluxDB Cloud regions](/influxdb/cloud/reference/regions/) + or [InfluxDB OSS URLs](/influxdb/v2.1/reference/urls/))_ + + ``` + http://localhost:8086 + ``` + + - **Connection Name:** Name to uniquely identify this connection configuration + - **Organization:** InfluxDB [organization](/influxdb/v2.1/organizations/) + - **Token:** InfluxDB [API token](/influxdb/v2.1/security/tokens/) + - **Telegraf Database Name:** InfluxDB [bucket](/influxdb/v2.1/organizations/buckets/) + Chronograf uses to populate parts of the application, including the Host List page (default is `telegraf`) + - **Default Retention Policy:** default [retention policy](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#retention-policy-rp) + _**(leave blank)**_ + + {{% note %}} +#### DBRPs map to InfluxDB buckets +In InfluxDB Cloud and InfluxDB OSS {{< current-version >}}, database/retention-policy (DBRP) combinations +are mapped to buckets using the `database-name/retention-policy` naming convention. +**DBRP mappings are required to query InfluxDB OSS 2.x or InfluxDB Cloud using InfluxQL.** + +For information, see [DBRP mapping](/influxdb/v2.1/reference/api/influxdb-1x/dbrp/) +and [Map unmapped buckets](/influxdb/v2.1/query-data/influxql/#map-unmapped-buckets). + {{% /note %}} + +3. Click **Add Connection**. +4. Select the dashboards you would like to create, and then click **Next**. +5. To configure a Kapacitor connection, provide the necessary credentials, + and then click **Continue**. Otherwise, click **Skip**. + _For information about using Kapacitor with InfluxDB Cloud or InfluxDB OSS {{< current-version >}}, + see [Use Kapacitor with InfluxDB](/influxdb/v2.1/tools/kapacitor/)._ +6. Click **Finish**. + +## Important notes + +- [Update upgraded InfluxDB connections](#Update-upgraded-InfluxDB-connections) +- [No administrative functionality](#No-administrative-functionality) +- [Limited InfluxQL support](#Limited-InfluxQL-support) + +### Update upgraded InfluxDB connections +If using Chronograf with an InfluxDB instance that was upgraded from 1.x +to 2.x, update your InfluxDB connection configuration in Chronograf to use the +**InfluxDB v2 Auth** option and provide an organization and a token. +**Without an organization, Chronograf cannot use Flux to query InfluxDB.** + +### No administrative functionality +Chronograf cannot be used for administrative tasks in InfluxDB Cloud and InfluxDB OSS {{< current-version >}}. +For example, you **cannot** do the following: + +- Define databases +- Modify retention policies +- Add users +- Kill queries + +When connected to an InfluxDB Cloud or InfluxDB {{< current-version >}} database, functionality in the +**{{< icon "crown" >}} InfluxDB Admin** section of Chronograf is disabled. + +To complete administrative tasks, use the following: + +- **InfluxDB user interface (UI)** +- [InfluxDB CLI](/influxdb/v2.1/reference/cli/influx/) +- [InfluxDB v2 API](/influxdb/v2.1/reference/api/) + +### Limited InfluxQL support +InfluxDB Cloud and InfluxDB OSS {{< current-version >}} support InfluxQL **read-only** queries. +For more information, see [InfluxQL support](/influxdb/v2.1/query-data/influxql/#influxql-support). + diff --git a/content/influxdb/v2.1/tools/flux-vim-lsp.md b/content/influxdb/v2.1/tools/flux-vim-lsp.md new file mode 100644 index 0000000000..99a756fe5a --- /dev/null +++ b/content/influxdb/v2.1/tools/flux-vim-lsp.md @@ -0,0 +1,111 @@ +--- +title: Use the Flux LSP with Vim +description: > + Use the Flux LSP with Vim to add auto-completion, syntax checking, and other language-specific features to your editor. +menu: + influxdb_2_1: + parent: Tools & integrations +weight: 102 +--- + +## Requirements + +- Vim 8+ +- [npm](https://www.npmjs.com/get-npm) + +## Install the Flux plugin + +There are many ways to install and manage Vim plugins. +We recommend either of the following two methods: + +- [Install with vim-lsp](#install-with-vim-lsp) +- [Install with vim-coc](#install-with-vim-coc) + +Both methods require you to add the following to your `.vimrc` so that Vim can recognize the `.flux` file type: + +``` +" Flux file type +au BufRead,BufNewFile *.flux set filetype=flux +``` + +### Install with vim-lsp + +1. **Install `flux-lsp-cli` with npm** + + ```sh + npm i -g @influxdata/flux-lsp-cli + ``` + +2. **Install [vim-lsp](https://github.com/prabirshrestha/vim-lsp)** + + If it doesn't exist yet, create a directory called `pack/$USER/start/` in your `~/.vim/` and clone `vim-lsp` into it: + + ```sh + cd ~ + mkdir -p .vim/pack/$USER/start/ + cd .vim/pack/$USER/start/ + git clone https://github.com/prabirshrestha/vim-lsp + ``` + +3. **Edit your `.vimrc`** + + Next, edit your `.vimrc` configuration file to include the following: + + ``` + let g:lsp_diagnostics_enabled = 1 + + if executable('flux-lsp') + au User lsp_setup call lsp#register_server({ + \ 'name': 'flux lsp', + \ 'cmd': {server_info->[&shell, &shellcmdflag, 'flux-lsp']}, + \ 'whitelist': ['flux'], + \ }) + endif + + autocmd FileType flux nmap gd (lsp-definition) + ``` + +### Install with vim-coc + +1. **Install `flux-lsp-cli` from npm** + + ```sh + npm i -g @influxdata/flux-lsp-cli + ``` +2. **Install plug-vim** + + [Install plug-vim](https://github.com/junegunn/vim-plug#installation), a plugin manager for Vim. + +3. **Install vim-coc** + + [Install vim-coc](https://github.com/neoclide/coc.nvim#quick-start), a code-completion plugin for Vim. + +4. **Configure vim-coc** + + vim-coc uses a `coc-settings.json` located in your `~/.vim/` directory. + To run the Flux LSP, add the Flux section under `languageserver`: + + ```json + { + "languageserver": { + "flux": { + "command": "flux-lsp", + "filetypes": ["flux"] + } + } + } + ``` + + To debug flux-lsp, configure it to log to `/tmp/fluxlsp`: + + ```json + { + "languageserver": { + "flux": { + "command": "flux-lsp", + "args": ["-l", "/tmp/fluxlsp"], + "filetypes": ["flux"] + } + } + } + ``` diff --git a/content/influxdb/v2.1/tools/flux-vscode.md b/content/influxdb/v2.1/tools/flux-vscode.md new file mode 100644 index 0000000000..66c0ca6632 --- /dev/null +++ b/content/influxdb/v2.1/tools/flux-vscode.md @@ -0,0 +1,83 @@ +--- +title: Use the Flux VS Code extension +seotitle: Use the Flux Visual Studio Code extension +description: > + The [Flux Visual Studio Code (VS Code) extension](https://marketplace.visualstudio.com/items?itemName=influxdata.flux) + provides Flux syntax highlighting, autocompletion, and a direct InfluxDB OSS server + integration that lets you run Flux scripts natively and show results in VS Code. +weight: 103 +menu: + influxdb_2_1: + name: Use the Flux VS Code extension + parent: Tools & integrations +--- + +The [Flux Visual Studio Code (VS Code) extension](https://marketplace.visualstudio.com/items?itemName=influxdata.flux) +provides Flux syntax highlighting, autocompletion, and a direct InfluxDB server +integration that lets you run Flux scripts natively and show results in VS Code. + +##### On this page +- [Install the Flux VS Code extension](#install-the-flux-vs-code-extension) +- [Connect to InfluxDB](#connect-to-influxdb) +- [Query InfluxDB from VS Code](#query-influxdb-from-vs-code) +- [Explore your schema](#explore-your-schema) +- [Debug Flux queries](#debug-flux-queries) +- [Upgrade the Flux extension](#upgrade-the-flux-extension) +- [Flux extension commands](#flux-extension-commands) + +## Install the Flux VS Code extension +The Flux VS Code extension is available in the **Visual Studio Marketplace**. +For information about installing extensions from the Visual Studio marketplace, +see the [Extension Marketplace documentation](https://code.visualstudio.com/docs/editor/extension-gallery). + +## Connect to InfluxDB +To create an InfluxDB connection in VS Code: + +1. Open the **VS Code Command Pallet** ({{< keybind mac="⇧⌘P" other="Ctrl+Shift+P" >}}). +2. Run `influxdb.addConnection`. +3. Provide the required connection credentials: + - **Type:** type of InfluxDB data source. Select **InfluxDB v2**. + - **Name:** unique identifier for your InfluxDB connection. + - **Hostname and Port:** InfluxDB host and port + (see [InfluxDB OSS URLs](/influxdb/v2.1/reference/urls/) or [InfluxDB Cloud regions](/influxdb/cloud/reference/regions/)). + - **Token:** InfluxDB [API token](/influxdb/v2.1/security/tokens/). + - **Organization:** InfluxDB organization name. +4. Click **Test** to test the connection. +5. Once tested successfully, click **Save**. + +## Query InfluxDB from VS Code +1. Write your Flux query in a new VS Code file. +2. Save your Flux script with the `.flux` extension or set the + [VS Code Language Mode](https://code.visualstudio.com/docs/languages/overview#_changing-the-language-for-the-selected-file) to **Flux**. +3. Execute the query with the `influxdb.runQuery` command or {{< keybind mac="⌃⌥E" other="Ctrl+Alt+E" >}}. +4. Query results appear in a new tab. If query results do not appear, see [Debug Flux queries](#debug-flux-queries). + +## Explore your schema +After you've configured an InfluxDB connection, VS Code provides an overview of buckets, +measurements, and tags in your InfluxDB organization. +Use the **InfluxDB** pane in VS code to explore your schema. + +{{< img-hd src="/img/influxdb/2-0-tools-vsflux-explore-schema.png" alt="Explore your InfluxDB schema in VS Code" />}} + +## Debug Flux queries +To view errors returned from Flux script executions, click the **Errors and Warnings** +icons in the bottom left of your VS Code window, and then select the **Output** tab in the debugging pane. + +{{< img-hd src="/img/influxdb/2-0-tools-vsflux-errors-warnings.png" alt="VS Code errors and warnings"/>}} + +## Upgrade the Flux extension +VS Code auto-updates extensions by default, but you are able to disable auto-update. +If you disable auto-update, [manually update your VS Code Flux extension](https://code.visualstudio.com/docs/editor/extension-gallery#_update-an-extension-manually). +After updating the extension, reload your VS Code window ({{< keybind mac="⇧⌘P" other="Ctrl+Shift+P" >}}, +and then `Reload Window`) to initialize the updated extensions. + +## Flux extension commands + +| Command | Description | Keyboard shortcut | Menu context | +|:------- |:----------- |:-----------------: | ------------: | +| `influxdb.refresh` | Refresh | | | +| `influxdb.addConnection` | Add Connection | | view/title | +| `influxdb.runQuery` | Run Query | {{< keybind mac="⌃⌥E" other="Ctrl+Alt+E" >}} | editor/context | +| `influxdb.removeConnection` | Remove Connection | | view/item/context | +| `influxdb.switchConnection` | Switch Connection | | | +| `influxdb.editConnection` | Edit Connection | | view/item/context | diff --git a/content/influxdb/v2.1/tools/google-data-studio.md b/content/influxdb/v2.1/tools/google-data-studio.md new file mode 100644 index 0000000000..60a2479bfe --- /dev/null +++ b/content/influxdb/v2.1/tools/google-data-studio.md @@ -0,0 +1,35 @@ +--- +title: Use the Google Data Studio connector +description: > + The [InfluxDB Google Data Studio connector](https://datastudio.google.com/u/0/datasources/create?connectorId=AKfycbwhJChhmMypQvNlihgRJMAhCb8gaM3ii9oUNWlW_Cp2PbJSfqeHfPyjNVp15iy9ltCs) + lets you create reports and dashboards in Google Data Studio with data from + InfluxDB Cloud or InfluxDB OSS 2.x. +menu: + influxdb_2_1: + parent: Tools & integrations +weight: 104 +influxdb/v2.1/tags: [google] +--- + +The [InfluxDB Google Data Studio connector](https://datastudio.google.com/u/0/datasources/create?connectorId=AKfycbwhJChhmMypQvNlihgRJMAhCb8gaM3ii9oUNWlW_Cp2PbJSfqeHfPyjNVp15iy9ltCs) lets you create reports and dashboards in Google Data Studio with data from **InfluxDB Cloud** or **InfluxDB OSS {{< current-version >}}**. The connector supports one measurement per organization. + +### Add the InfluxDB Connector to Data Studio + +1. Add the [InfluxDB Connector data source](https://datastudio.google.com/u/0/datasources/create?connectorId=AKfycbwhJChhmMypQvNlihgRJMAhCb8gaM3ii9oUNWlW_Cp2PbJSfqeHfPyjNVp15iy9ltCs). +2. Enter the following connection details: + - `InfluxDB URL`: Your [InfluxDB URL](/influxdb/v2.1/reference/urls/). + - `Token`: Your [API token](/influxdb/v2.1/security/tokens/create-token/) with permission to read from the bucket you're using. + - `Organization`: Your [organization name](/influxdb/v2.1/organizations/view-orgs). + - `Bucket`: Your [bucket name](/influxdb/v2.1/organizations/buckets/view-buckets/). This is auto-populated when you enter the fields above. + - `Measurement`: The [measurement](/influxdb/v2.1/reference/glossary/#measurement) to connect to. +3. Click **Connect**. + +### Create a report of InfluxDB data in Data Studio + +1. Once you're connected, a list of fields available from your measurement, including the [tag set](/influxdb/v2.1/reference/glossary/#tag-set), [field set](/influxdb/v2.1/reference/glossary/#field-set), and [timestamp](/influxdb/v2.1/reference/glossary/#timestamp) appear. Review the list of fields and [edit as needed](https://support.google.com/datastudio/answer/7000529?hl=en&ref_topic=6370331). +2. Click **CREATE REPORT** to [create the report](https://support.google.com/datastudio/topic/6369007?hl=en&ref_topic=6291037). +3. Customize the [visualization in your report](https://support.google.com/datastudio/?hl=en#topic=6291037). + +### Example use case with COVID-19 data + +For an example of how to use this connector, see a [COVID-19 report powered by InfluxDB](https://github.com/influxdata/influxdb-gds-connector/tree/master/examples). diff --git a/content/influxdb/v2.1/tools/grafana.md b/content/influxdb/v2.1/tools/grafana.md new file mode 100644 index 0000000000..3dfae4005e --- /dev/null +++ b/content/influxdb/v2.1/tools/grafana.md @@ -0,0 +1,256 @@ +--- +title: Use Grafana with InfluxDB OSS +description: > + Use [Grafana](https://grafana.com/) to visualize data from your **InfluxDB** instance. +menu: + influxdb_2_1: + name: Use Grafana + parent: Tools & integrations +weight: 104 +influxdb/v2.1/tags: [grafana] +aliases: + - /influxdb/v2.1/visualize-data/other-tools/grafana/ +related: + - https://grafana.com/docs/, Grafana documentation + - /influxdb/v2.1/query-data/get-started/ +--- + +Use [Grafana](https://grafana.com/) or [Grafana Cloud](https://grafana.com/products/cloud/) +to visualize data from your **InfluxDB** instance. + +{{% note %}} +The instructions in this guide require **Grafana Cloud** or **Grafana v7.1+**. +{{% /note %}} + +1. [Start InfluxDB OSS {{< current-version >}}](/influxdb/v2.1/install/#start-influxdb). +2. [Sign up for Grafana Cloud](https://grafana.com/products/cloud/) or + [download and install Grafana](https://grafana.com/grafana/download). +3. Visit your **Grafana Cloud user interface** (UI) or, if running Grafana locally, + [start Grafana](https://grafana.com/docs/grafana/latest/installation/) and visit + `http://localhost:3000` in your browser. +4. In the left navigation of the Grafana UI, hover over the gear + icon to expand the **Configuration** section. Click **Data Sources**. +5. Click **Add data source**. +6. Select **InfluxDB** from the list of available data sources. +7. On the **Data Source configuration page**, enter a **name** for your InfluxDB data source. +8. Under **Query Language**, select one of the following: + +{{< tabs-wrapper >}} +{{% tabs %}} +[Flux](#) +[InfluxQL](#) +{{% /tabs %}} +{{% tab-content %}} +## Configure Grafana to use Flux + +With **Flux** selected as the query language in your InfluxDB data source, +configure your InfluxDB connection: + +1. Under **Connection**, enter the following: + + - **URL**: Your [InfluxDB URL](/influxdb/v2.1/reference/urls/). + + ```sh + http://localhost:8086/ + ``` + + - **Organization**: Your InfluxDB [organization name **or** ID](/influxdb/v2.1/organizations/view-orgs/). + - **Token**: Your InfluxDB [API token](/influxdb/v2.1/security/tokens/). + - **Default Bucket**: The default [bucket](/influxdb/v2.1/organizations/buckets/) to use in Flux queries. + - **Min time interval**: The [Grafana minimum time interval](https://grafana.com/docs/grafana/latest/features/datasources/influxdb/#min-time-interval). + + {{< img-hd src="/img/influxdb/2-0-tools-grafana.png" />}} + +2. Click **Save & Test**. Grafana attempts to connect to the InfluxDB {{< current-version >}} datasource + and returns the results of the test. +{{% /tab-content %}} + + +{{% tab-content %}} + +## Configure Grafana to use InfluxQL + +To query InfluxDB OSS {{< current-version >}} with InfluxQL, find your use case below, and then complete the instructions to configure Grafana: + +- [Installed a new InfluxDB {{< current-version >}} instance](#installed-a-new-influxdb-instance) +- [Upgraded from InfluxDB 1.x to {{< current-version >}} (following the official upgrade)](#upgraded-from-influxdb-1x-to-2x) +- [Manually migrated from InfluxDB 1.x to {{< current-version >}}](#manually-migrated-from-influxdb-1x-to-2x) + +### Installed a new InfluxDB instance +To configure Grafana to use InfluxQL with a new install of InfluxDB {{< current-version >}}, do the following: + +1. [Authenticate with InfluxDB {{< current-version >}} tokens](/influxdb/v2.1/security/tokens/). +2. [Manually create DBRP mappings](#view-and-create-influxdb-dbrp-mappings). + +### Upgraded from InfluxDB 1.x to 2.x +To configure Grafana to use InfluxQL when you've upgraded from InfluxDB 1.x to +InfluxDB {{< current-version >}} (following an [official upgrade guide](/influxdb/v2.1/upgrade/v1-to-v2/)): + +1. Authenticate using the _non-admin_ [v1 compatible authentication credentials](#view-and-create-influxdb-v1-authorizations) + created during the upgrade process. +2. Use the DBRP mappings InfluxDB automatically created in the upgrade process (no action necessary). + +### Manually migrated from InfluxDB 1.x to 2.x +To configure Grafana to use InfluxQL when you've manually migrated from InfluxDB +1.x to InfluxDB {{< current-version >}}, do the following: + +1. If your InfluxDB 1.x instance required authentication, + [create v1 compatible authentication credentials](#view-and-create-influxdb-v1-authorizations) + to match your previous 1.x username and password. + Otherwise, use [InfluxDB v2 token authentication](/influxdb/v2.1/security/tokens/). +2. [Manually create DBRP mappings](#view-and-create-influxdb-dbrp-mappings). + +{{< expand-wrapper >}} +{{% expand "View and create InfluxDB v1 authorizations" %}} + +InfluxDB OSS {{< current-version >}} provides a 1.x compatible authentication API that lets you +authenticate with a username and password like InfluxDB 1.x +_(separate from the credentials used to log into the InfluxDB user interface)_. + +#### View existing v1 authorizations +Use the [`influx v1 auth list`](/influxdb/v2.1/reference/cli/influx/v1/auth/list/) +to list existing InfluxDB v1 compatible authorizations. + +```sh +influx v1 auth list +``` + +#### Create a v1 authorization +Use the [`influx v1 auth create` command](/influxdb/v2.1/reference/cli/influx/v1/auth/create/) +to grant read/write permissions to specific buckets. Provide the following: + +- [bucket IDs](/influxdb/v2.1/organizations/buckets/view-buckets/) to grant read + or write permissions to +- new username +- new password _(when prompted)_ + + +```sh +influx v1 auth create \ + --read-bucket 00xX00o0X001 \ + --write-bucket 00xX00o0X001 \ + --username example-user +``` +{{% /expand %}} +{{< expand "View and create InfluxDB DBRP mappings" >}} + +When using InfluxQL to query InfluxDB, the query must specify a database and a retention policy. +InfluxDB DBRP mappings associate database and retention policy combinations with +InfluxDB {{< current-version >}} [buckets](/influxdb/v2.1/reference/glossary/#bucket). + +DBRP mappings do not affect the retention period of the target bucket. +These mappings allow queries following InfluxDB 1.x conventions to successfully +query InfluxDB {{< current-version >}} buckets. + +#### View existing DBRP mappings +Use the [`influx v1 dbrp list`](/influxdb/v2.1/reference/cli/influx/v1/dbrp/list/) +to list existing DBRP mappings. + +```sh +influx v1 dbrp list +``` + +#### Create a DBRP mapping +Use the [`influx v1 dbrp create` command](/influxdb/v2.1/reference/cli/influx/v1/dbrp/create/) +command to create a DBRP mapping. +Provide the following: + +- database name +- retention policy name _(not retention period)_ +- [bucket ID](/influxdb/v2.1/organizations/buckets/view-buckets/) +- _(optional)_ `--default` flag if you want the retention policy to be the default retention + policy for the specified database + +#### Examples + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[DB with one RP](#) +[DB with multiple RPs](#) +{{% /code-tabs %}} +{{< code-tab-content >}} +```sh +influx v1 dbrp create \ + --db example-db \ + --rp example-rp \ + --bucket-id 00xX00o0X001 \ + --default +``` +{{< /code-tab-content >}} +{{< code-tab-content >}} +```sh +# Create telegraf/autogen DBRP mapping with autogen +# as the default RP for the telegraf DB + +influx v1 dbrp create \ + --db telegraf \ + --rp autogen \ + --bucket-id 00xX00o0X001 \ + --default + +# Create telegraf/downsampled-daily DBRP mapping that +# writes to a different bucket + +influx v1 dbrp create \ + --db telegraf \ + --rp downsampled-daily \ + --bucket-id 00xX00o0X002 +``` +{{< /code-tab-content >}} +{{< /code-tabs-wrapper >}} + +_For more information about DBRP mapping, see [Database and retention policy mapping](/influxdb/v2.1/reference/api/influxdb-1x/dbrp/)._ +{{< /expand >}} +{{< /expand-wrapper >}} + +### Configure your InfluxDB connection +With **InfluxQL** selected as the query language in your InfluxDB data source settings: + +1. Under **HTTP**, enter the following: + + - **URL**: Your [InfluxDB URL](/influxdb/v2.1/reference/urls/). + + ```sh + http://localhost:8086/ + ``` + - **Access**: Server (default) + +2. Configure InfluxDB authentication: + + - ##### Token authentication + + Under **Custom HTTP Headers**, select **Add Header**. Provide your InfluxDB API token: + + - **Header**: Enter `Authorization` + - **Value**: Use the `Token` schema and provide your [InfluxDB API token](/influxdb/v2.1/security/tokens/). + For example: + + ``` + Token y0uR5uP3rSecr3tT0k3n + ``` + + - ##### Authenticate with username and password + + Under **InfluxDB Details**, do the following: + + - **Database**: Enter the database name [mapped to your InfluxDB {{< current-version >}} bucket](#view-and-create-influxdb-dbrp-mappings) + - **User**: Enter the username associated with your [InfluxDB 1.x compatibility authorization](#view-and-create-influxdb-v1-authorizations) + - **Password**: Enter the password associated with your [InfluxDB 1.x compatibility authorization](#view-and-create-influxdb-dbrp-mappings) + - **HTTP Method**: Select **GET** + + + {{< img-hd src="/img/influxdb/2-0-tools-grafana-influxql.png" />}} + +3. Click **Save & Test**. Grafana attempts to connect to the InfluxDB {{< current-version >}} data source + and returns the results of the test. +{{% /tab-content %}} + +{{< /tabs-wrapper >}} + +## Query and visualize data + +With your InfluxDB connection configured, use Grafana and Flux to query and +visualize time series data stored in your **InfluxDB** instance. + +For more information about using Grafana, see the [Grafana documentation](https://grafana.com/docs/). +If you're just learning Flux, see [Get started with Flux](/{{< latest "flux" >}}/get-started/). diff --git a/content/influxdb/v2.1/tools/influx-cli.md b/content/influxdb/v2.1/tools/influx-cli.md new file mode 100644 index 0000000000..78f0fa1c00 --- /dev/null +++ b/content/influxdb/v2.1/tools/influx-cli.md @@ -0,0 +1,230 @@ +--- +title: Install and use the influx CLI +description: + Use the `influx` and `influxd` command line interfaces to interact with and + manage InfluxDB. +menu: + influxdb_2_1: + name: Use the influx CLI + parent: Tools & integrations + identifier: influx-cli-task-based +weight: 101 +influxdb/v2.1/tags: [cli] +aliases: + - /influxdb/v2.1/tools/clis/ +related: + - /influxdb/v2.1/reference/cli/influx/ +--- + +Use the `influx` CLI to interact with and manage your +InfluxDB {{% cloud-only %}}Cloud{{% /cloud-only %}} instance. +Write and query data, generate InfluxDB templates, export data, and more. + +{{% oss-only %}} + +{{% note %}} +The [`influx` CLI](/influxdb/v2.1/reference/cli/influx) is packaged and versioned +separately from the InfluxDB server (`influxd`). +{{% /note %}} + +{{% /oss-only %}} + +- [Install the influx CLI](#install-the-influx-cli) +- [Set up the influx CLI](#set-up-the-influx-cli) +- [Use influx CLI commands](#use-influx-cli-commands) + +## Install the influx CLI + +{{< tabs-wrapper >}} +{{% tabs %}} +[macOS](#) +[Linux](#) +[Windows](#) +{{% /tabs %}} + + +{{% tab-content %}} + +Do one of the following: + +- [Use Homebrew](#use-homebrew) +- [Manually download and install](#manually-download-and-install) + +### Use Homebrew +```sh +brew install influxdb-cli +``` + +{{% oss-only %}} + +{{% note %}} +If you used Homebrew to install **InfluxDB v{{< current-version >}}**, the `influxdb-cli` +formula was downloaded as a dependency and should already be installed. +If installed, `influxdb-cli` will appear in the output of the following command: + +```sh +brew list | grep influxdb-cli +``` +{{% /note %}} + +{{% /oss-only %}} + +### Manually download and install + +1. **Download the `influx` CLI package.** + + influx CLI v{{< latest-patch cli=true >}} (macOS) + +2. **Unpackage the downloaded package.** + + Do one of the following: + + - Double-click the downloaded package file in **Finder**. + - Run the following command in a macOS command prompt application such + **Terminal** or **[iTerm2](https://www.iterm2.com/)**: + + ```sh + # Unpackage contents to the current working directory + tar zxvf ~/Downloads/influxdb2-client-{{< latest-patch cli=true >}}-darwin-amd64.tar.gz + ``` + +3. **(Optional) Place the binary in your `$PATH`.** + + ```sh + # (Optional) Copy the influx binary to your $PATH + sudo cp ~/Downloads/influxdb2-client-{{< latest-patch cli=true >}}-darwin-amd64/influx /usr/local/bin/ + ``` + + If you do not move the `influx` binary into your `$PATH`, prefix the executable + `./` to run it in place. + +4. **(macOS Catalina and newer) Authorize the `influx` binary.** + + macOS requires downloaded binaries to be signed by registered Apple developers. + When you first attempt to run `influx`, macOS will prevent it from running. + To authorize the `influx` binary: + + 1. Attempt to run an `influx` command. + 2. Open **System Preferences** and click **Security & Privacy**. + 3. Under the **General** tab, there is a message about `influx` being blocked. + Click **Open Anyway**. + +{{% /tab-content %}} + + + +{{% tab-content %}} + +1. **Download the influx CLI package.** + + Download the `influx` CLI package [from your browser](#download-from-your-browser) + or [from the command line](#download-from-the-command-line). + + #### Download from your browser + + influx CLI v{{< latest-patch cli=true >}} (amd64) + influx CLI v{{< latest-patch cli=true >}} (arm) + + #### Download from the command line + + ```sh + # amd64 + wget https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-linux-amd64.tar.gz + + # arm + wget https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-linux-arm64.tar.gz + ``` + +4. **Unpackage the downloaded package.** + + _**Note:** The following commands are examples. Adjust the filenames, paths, and utilities if necessary._ + + ```sh + # amd64 + tar xvzf path/to/influxdb2-client-{{< latest-patch cli=true >}}-linux-amd64.tar.gz + + # arm + tar xvzf path/to/influxdb2-client-{{< latest-patch cli=true >}}-linux-arm64.tar.gz + ``` + +3. **(Optional) Place the unpackaged `influx` executable in your system `$PATH`.** + + ```sh + # amd64 + sudo cp influxdb2-client-{{< latest-patch cli=true >}}-linux-amd64/influx /usr/local/bin/ + + # arm + sudo cp influxdb2-client-{{< latest-patch cli=true >}}-linux-amd64/influx /usr/local/bin/ + ``` + + If you do not move the `influx` binary into your `$PATH`, prefix the executable + `./` to run it in place. + +{{% /tab-content %}} + + + +{{% tab-content %}} + +1. **Download the `influx` CLI package.** + + influx CLI v{{< latest-patch cli=true >}} (Windows) + +2. **Expand the downloaded archive.** + + Expand the downloaded archive into `C:\Program Files\InfluxData\` and rename it if desired. + + ```powershell + > Expand-Archive .\influxdb2-client-{{< latest-patch cli=true >}}-windows-amd64.zip -DestinationPath 'C:\Program Files\InfluxData\' + > mv 'C:\Program Files\InfluxData\influxdb2-{{< latest-patch cli=true >}}-windows-amd64' 'C:\Program Files\InfluxData\influx' + ``` + +3. **Grant network access to the `influx` CLI.** + + When using the `influx` CLI for the first time, **Windows Defender** displays + the following message: + + > Windows Defender Firewall has blocked some features of this app. + + To grant the `influx` CLI the required access, do the following: + + 1. Select **Private networks, such as my home or work network**. + 2. Click **Allow access**. + +{{% /tab-content %}} + +{{< /tabs-wrapper >}} + +## Set up the influx CLI + +- [Provide required authentication credentials](#provide-required-authentication-credentials) +- [Enable shell completion (Optional)](#enable-shell-completion-optional) + +### Provide required authentication credentials +To avoid having to pass your InfluxDB **host**, **API token**, and **organization** +with each command, store them in an `influx` CLI configuration (config). +`influx` commands that require these credentials automatically retrieve these +credentials from the active config. + +Use the [`influx config create` command](/influxdb/v2.1/reference/cli/influx/config/create/) +to create an `influx` CLI config and set it as active: + +```sh +influx config create --config-name \ + --host-url http://localhost:8086 \ + --org \ + --token \ + --active +``` + +For more information about managing CLI configurations, see the +[`influx config` documentation](/influxdb/v2.1/reference/cli/influx/config/). + +### Enable shell completion (Optional) + +To install `influx` shell completion scripts, see +[`influx completion`](/influxdb/v2.1/reference/cli/influx/completion/#install-completion-scripts). + +## Use influx CLI commands +_For information about `influx` CLI commands, see the +[`influx` CLI reference documentation](/influxdb/v2.1/reference/cli/influx/)._ diff --git a/content/influxdb/v2.1/tools/kapacitor.md b/content/influxdb/v2.1/tools/kapacitor.md new file mode 100644 index 0000000000..2f503cf23b --- /dev/null +++ b/content/influxdb/v2.1/tools/kapacitor.md @@ -0,0 +1,139 @@ +--- +title: Use Kapacitor with InfluxDB OSS +description: > + [Kapacitor](/kapacitor/) is a data processing framework that makes it easy to + create alerts, run ETL (Extract, Transform and Load) jobs and detect anomalies. + Use Kapacitor with **InfluxDB OSS 2.x**. +menu: + influxdb_2_1: + name: Use Kapacitor + parent: Tools & integrations +weight: 102 +related: + - /{{< latest "kapacitor" >}}/ +--- + +[Kapacitor](/{{< latest "kapacitor" >}}/) is a data processing framework that makes +it easy to create alerts, run ETL jobs and detect anomalies. +Kapacitor interacts with **InfluxDB Cloud** and **InfluxDB OSS {{< current-version >}}** using the +[InfluxDB 1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/), so +you can continue using Kapacitor without having to migrate libraries of TICKscripts +to InfluxDB tasks. + +{{% note %}} +#### Support for stream tasks +InfluxDB Cloud and InfluxDB OSS {{< current-version >}} do not have subscription APIs and +**do not support Kapacitor stream tasks**, but you can continue to use stream +tasks by writing data directly to Kapacitor. +For more information, see [below](#use-kapacitor-stream-tasks). +{{% /note %}} + +#### On this page +- [Configure Kapacitor to connect to InfluxDB](#configure-kapacitor-to-connect-to-influxdb) +- [Use Kapacitor batch tasks](#use-kapacitor-batch-tasks) +- [Use Kapacitor stream tasks](#use-kapacitor-stream-tasks) +- [Write back to InfluxDB](#write-back-to-influxdb) + +## Configure Kapacitor to connect to InfluxDB +To connect Kapacitor to InfluxDB Cloud or InfluxDB OSS {{< current-version >}}, update the `[[influxdb]]` +section(s) of your [Kapacitor configuration file](/{{< latest "kapacitor" >}}/administration/configuration/#kapacitor-configuration-file): + +- [Specify your InfluxDB URL](#specify-your-influxdb-url) +- [Provide InfluxDB authentication credentials](#provide-influxdb-authentication-credentials) +- [Disable InfluxDB subcriptions](#disable-influxdb-subscriptions) + +### Specify your InfluxDB URL +Provide your InfluxDB URL in the `[[influxdb]].urls` configuration option. +For more information, see [InfluxDB Cloud regions](/influxdb/cloud/reference/regions/) +or [InfluxDB OSS URLs](/influxdb/v2.1/reference/urls/). + +```toml +[[influxdb]] + # ... + urls = ["http://localhost:8086"] +``` + +### Provide InfluxDB authentication credentials +InfluxDB Cloud and InfluxDB OSS {{< current-version >}} require authentication. +Provide the following credentials in your `[[influxdb]].username` and `[[influxdb]].password` +configuration options: + +- **username:** InfluxDB username +- **password:** InfluxDB [API token](/influxdb/v2.1/security/tokens/) + +```toml +[[influxdb]] + # ... + username = "influxdb-username" + password = "influxdb-token" +``` + +{{% warn %}} +Kapacitor is subject to InfluxDB token permission restrictions. +To query or write to an InfluxDB bucket, the InfluxDB token must have read and/or +write permissions for the target bucket. +For information about token permissions, see [Create a token](/influxdb/v2.1/security/tokens/create-token/). +{{% /warn %}} + +### Disable InfluxDB subscriptions +InfluxDB Cloud and InfluxDB OSS {{< current-version >}} do not have subscriptions APIs. +Set the `[[influxdb]].disable-subscriptions`to `true` to disable InfluxDB subscriptions. + +```toml +[[influxdb]] + # ... + disable-subscriptions = true +``` + +## Use Kapacitor batch tasks +Kapacitor batch tasks use the `query` endpoint of the 1.x compatibility API +and require no change to use with InfluxDB Cloud and InfluxDB OSS. +For information about writing back to InfluxDB in Kapacitor tasks, +see [Write back to InfluxDB](#write-back-to-influxdb) below. + +## Use Kapacitor stream tasks +InfluxDB Cloud and OSS {{< current-version >}} do not have subscription APIs and do not support Kapacitor stream tasks directly. +To use Kapacitor stream tasks, write data directly to Kapacitor using the [Kapcitior `write` API](/{{< latest "kapacitor" >}}/working/api/#writing-data). + +We recommend using [Telegraf InfluxDB output plugin](/{{< latest "telegraf" >}}/plugins/#influxdb) +to write data to both InfluxDB Cloud or OSS and Kapacitor. +The following example Telegraf configuration writes data to both InfluxDB and Kapacitor: + +##### Example Telegraf configuration +```toml +# Write to Kapacitor +[[outputs.influxdb]] + urls = ["http://localhost:9092"] + database = "example-db" + retention_policy = "example-rp" + +# Write to InfluxDB Cloud or OSS +[[outputs.influxdb]] + urls = ["http://localhost:8086"] + database = "example-db" + retention_policy = "example-rp" + username = "influxdb-username" + password = "influxdb-token" +``` + +## Write back to InfluxDB +If using the Kapacitor `InfluxDBOut` node to write data to InfluxDB Cloud or OSS {{< current-version >}}, +InfluxDB maps the specified database and retention policy to a corresponding bucket. +You can also manually map database/retention policy combinations (DBRPs) to buckets. +For more information, see [DBRP mapping](/influxdb/v2.1/reference/api/influxdb-1x/dbrp/) +and [Map unmapped buckets](/influxdb/v2.1/query-data/influxql/#map-unmapped-buckets). + +The following example TICKscript writes to the `my-db/my-rp` bucket in +InfluxDB Cloud or InfluxDB OSS {{< current-version >}}. + +```js +batch + |query('SELECT errors / total AS error_percent from requests') + // Write the transformed data to InfluxDB + |influxDBOut() + .database('my-db') + .retentionPolicy('my-rp') + .measurement('errors') + .tag('kapacitor', 'true') + .tag('version', '0.2') +``` diff --git a/content/influxdb/v2.1/tools/repl.md b/content/influxdb/v2.1/tools/repl.md new file mode 100644 index 0000000000..2af07f8053 --- /dev/null +++ b/content/influxdb/v2.1/tools/repl.md @@ -0,0 +1,53 @@ +--- +title: Use the Interactive Flux REPL +description: > + Use the Flux REPL (Read–Eval–Print Loop) to execute Flux scripts and interact + with InfluxDB and other data sources. +influxdb/v2.1/tags: [flux] +menu: + influxdb_2_1: + name: Use the Flux REPL + parent: Tools & integrations +weight: 103 +--- + +Use the Flux REPL (Read–Eval–Print Loop) to execute Flux scripts and interact with InfluxDB and other data sources. +[Build the REPL](#build-the-repl) from the Flux source code. + +## Build the REPL + +To use the Flux REPL, build it from source using the [Flux repository](https://github.com/influxdata/flux/). +For instructions, see the [Flux repository README](https://github.com/influxdata/flux/#requirements). + +## Use the REPL + +- [Open a REPL session](#open-a-repl-session) +- [Query data from InfluxDB](#query-data-from-influxdb) +- [Multi-line entries](#multi-line-entries) +- [Exit the REPL](#exit-the-repl) + +### Open a REPL session +To open a new REPL session, run: + +```sh +./flux repl +``` + +### Query data from InfluxDB +To query data from InfluxDB (local or remote), provide the host, organization, and token parameters +to the [`from()` function](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/from/). + +```js + host: "http://localhost:8086", + org: "example-org", + token: "My5uP3rS3cRetT0k3n" +) +``` + +### Multi-line entries +Multi-line scripts like the example above work when pasted into the REPL. +Pasting newlines from the clipboard is allowed. +However, you cannot enter newline characters directly from the keyboard. + +### Exit the REPL +Exit the REPL by pressing **Control + D**. diff --git a/content/influxdb/v2.1/upgrade/_index.md b/content/influxdb/v2.1/upgrade/_index.md new file mode 100644 index 0000000000..0f2bd395f3 --- /dev/null +++ b/content/influxdb/v2.1/upgrade/_index.md @@ -0,0 +1,12 @@ +--- +title: Upgrade InfluxDB +description: > + Upgrade your version of InfluxDB +menu: influxdb_2_1 +weight: 3 +aliases: + - /influxdb/v2.1/reference/upgrading/ +influxdb/v2.1/tags: [upgrade] +--- + +{{< children >}} diff --git a/content/influxdb/v2.1/upgrade/downgrade.md b/content/influxdb/v2.1/upgrade/downgrade.md new file mode 100644 index 0000000000..a925aceaa9 --- /dev/null +++ b/content/influxdb/v2.1/upgrade/downgrade.md @@ -0,0 +1,42 @@ +--- +title: Downgrade InfluxDB +description: > + To downgrade from InfluxDB {{< current-version >}} to a previous 2.x version, + use the `influxd downgrade` command to downgrade the metadata schema used by + `influxd` to match the metadata schema of a older release. +menu: + influxdb_2_1: + parent: Upgrade InfluxDB + name: Downgrade InfluxDB +weight: 12 +related: + - /influxdb/v2.1/reference/cli/influxd/downgrade/ +--- + +To downgrade from InfluxDB {{< current-version >}} to a previous 2.x version, +use the `influxd downgrade` command to downgrade the metadata schema used by +`influxd` to match the metadata schema of a older release. + +InfluxDB does not guarantee backwards-compatibility with older releases in its embedded metadata stores. +Attempting to start an older `influxd` binary with a BoltDB or SQLite file that has +been migrated to a newer schema will result in a startup error similar to: + +``` +Error: up: reading migrations: migration "...": migration specification not found +``` + +**To downgrade from InfluxDB {{< current-version >}} to a previous 2.x version**: + +1. Run `influxd downgrade` using the **{{< current-version >}} `influxd` binary**. + Specify the previous InfluxDB version to downgrade to. + For example, to downgrade to InfluxDB 2.0: + + ```sh + influxd downgrade 2.0 + ``` + +2. Install the **earlier version** of InfluxDB: + + {{< influxdb/install-old-versions >}} + +3. Start InfluxDB with the **earlier versioned `influxd` binary**. diff --git a/content/influxdb/v2.1/upgrade/v1-to-v2/_index.md b/content/influxdb/v2.1/upgrade/v1-to-v2/_index.md new file mode 100644 index 0000000000..7302e23103 --- /dev/null +++ b/content/influxdb/v2.1/upgrade/v1-to-v2/_index.md @@ -0,0 +1,28 @@ +--- +title: Upgrade from InfluxDB 1.x to 2.1 +description: > + Explore different methods for upgrading from InfluxDB 1.x to InfluxDB 2.1 and + choose the best one for your use case. +menu: + influxdb_2_1: + parent: Upgrade InfluxDB + name: InfluxDB 1.x to 2.1 +weight: 11 +--- + +Explore different methods for upgrading from InfluxDB 1.x to InfluxDB {{< current-version >}} and +determine which best suits your use case. +Consider the following: + +#### Do you want to migrate all your time series data? +[Automatically upgrade to InfluxDB {{< current-version >}}](/influxdb/v2.1/upgrade/v1-to-v2/automatic-upgrade/). + +#### Do you want to selectively migrate your time series data? +[Manually upgrade to InfluxDB {{< current-version >}}](/influxdb/v2.1/upgrade/v1-to-v2/manual-upgrade/). + +#### Are you using Docker? +[Upgrade to the 2.x Docker image](/influxdb/v2.1/upgrade/v1-to-v2/docker/). + +#### Are you using continuous queries (CQs)? +After you upgrade (automatically, manually, or using Docker), +[migrate your 1.x CQs to InfluxDB {{< current-version >}} tasks](/influxdb/v2.1/upgrade/v1-to-v2/migrate-cqs/). diff --git a/content/influxdb/v2.1/upgrade/v1-to-v2/automatic-upgrade.md b/content/influxdb/v2.1/upgrade/v1-to-v2/automatic-upgrade.md new file mode 100644 index 0000000000..804b4af58a --- /dev/null +++ b/content/influxdb/v2.1/upgrade/v1-to-v2/automatic-upgrade.md @@ -0,0 +1,266 @@ +--- +title: Automatically upgrade from InfluxDB 1.x to 2.1 +list_title: Automatically upgrade from 1.x to 2.1 +description: > + Use the `influx upgrade` tool to automatically upgrade from InfluxDB 1.x to InfluxDB 2.1. +menu: + influxdb_2_1: + parent: InfluxDB 1.x to 2.1 + name: Automatically upgrade +weight: 10 +aliases: + - /influxdb/v2.1/reference/upgrading/influxd-upgrade-guide/ +related: + - /influxdb/v2.1/reference/cli/influxd/upgrade/ + - /influxdb/v2.1/upgrade/v1-to-v2/manual-upgrade/ + - /influxdb/v2.1/upgrade/v1-to-v2/docker/ +--- + +Use the `influxd upgrade` command to upgrade InfluxDB 1.x to InfluxDB {{< current-version >}}. +The `upgrade` command provides an in-place upgrade from InfluxDB 1.x to InfluxDB {{< current-version >}}. + +Specifically, the upgrade process does the following: + +1. Reads the existing InfluxDB 1.x configuration file and generates an equivalent InfluxDB {{< current-version >}} configuration file at `~/.influxdbv2/config.toml` or at a custom path specified with the `--v2-config-path` flag. +2. Upgrades metadata and storage engine paths to `~/.influxdbv2/meta` and `~/.influxdbv2/engine`, respectively (unless otherwise specified). +3. Writes existing data and write ahead log (WAL) files into InfluxDB {{< current-version >}} [buckets](/influxdb/v2.1/reference/glossary/#bucket). +4. Creates [database and retention policy (DBRP) mappings](/influxdb/v2.1/reference/api/influxdb-1x/dbrp/) required to query data with InfluxQL. +5. Reads existing metadata and migrates non-admin users, passwords, and permissions into a 1.x authorization–compatible store within `~/influxdbv2/influxdb.bolt`. + +When starting InfluxDB {{< current-version >}} after running `influxdb upgrade`, InfluxDB must build a new time series index (TSI). +Depending on the volume of data present, this may take some time. + +## Important considerations before you begin + +Before upgrading to InfluxDB {{< current-version >}}, consider the following guidelines. +Some or all might apply to your specific installation and use case. +The sections below contain our recommendations for addressing possible gaps in the upgrade process. +Consider whether you need to address any of the following before upgrading. + +- [Available operating system, container, and platform support](#available-operating-system-container-and-platform-support) +- [Continuous queries](#continuous-queries) +- [Supported protocols](#supported-protocols) +- [Kapacitor](#kapacitor) +- [User migration](#user-migration) +- [Dashboards](#dashboards) +- [Other data](#other-data) +- [Secure by default](#secure-by-default) +- [`inmem` indexing option](#in-memory-indexing-option) + +### Available operating system, container, and platform support + +InfluxDB {{< current-version >}} is currently available for macOS, Linux, and Windows. + +{{% note %}} +InfluxDB {{< current-version >}} requires 64-bit operating systems. +{{% /note %}} + +### Continuous queries + +Continuous queries are replaced by **tasks** in InfluxDB {{< current-version >}}. +By default, `influxd upgrade` writes all continuous queries to `~/continuous_queries.txt`. +To convert continuous queries to InfluxDB tasks, see +[Migrate continuous queries to tasks](/influxdb/v2.1/upgrade/v1-to-v2/migrate-cqs/). + +### Supported protocols + +InfluxDB {{< current-version >}} doesn't directly support the alternate write protocols +[supported in InfluxDB 1.x](/influxdb/v1.8/supported_protocols/) +(CollectD, Graphite, OpenTSDB, Prometheus, UDP). +Use [Telegraf](/{{< latest "telegraf" >}}/) to translate these protocols to line protocol. + +### Kapacitor + +You can continue to use Kapacitor with InfluxDB OSS {{< current-version >}} under the following scenarios: + +- Kapacitor Batch-style TICKscripts work with the 1.x read compatible API. + Existing Kapacitor user credentials should continue to work using the [1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). +- InfluxDB {{< current-version >}} has no subscriptions API and does not support Kapacitor stream tasks. + To continue using stream tasks, write data directly to both InfluxDB and Kapacitor. + Use **Telegraf** and its [InfluxDB output plugin](/{{< latest "telegraf" >}}/plugins/#influxdb) + to write to Kapacitor and the [InfluxDB v2 output plugin](/{{< latest "telegraf" >}}/plugins/#influxdb_v2) to write to InfluxDB v2. + +##### Example Telegraf configuration +```toml +# Write to Kapacitor +[[outputs.influxdb]] + urls = ["http://localhost:9092"] + database = "example-db" + retention_policy = "example-rp" + +# Write to InfluxDB {{< current-version >}} +[[outputs.influxdb]] + urls = ["http://localhost:8086"] + database = "example-db" + retention_policy = "example-rp" + username = "v1-auth-username" + password = "v1-auth-password" +``` + +### User migration + +`influxd upgrade` migrates existing 1.x users and their permissions **except** the following users: + +- [1.x admin users](/{{< latest "influxdb" "v1" >}}/administration/authentication_and_authorization/#admin-users) +- [1.x non-admin users](/{{< latest "influxdb" "v1" >}}/administration/authentication_and_authorization/#non-admin-users) + that have not been granted any privileges + +{{< expand-wrapper >}} +{{% expand "Review 1.x user privileges" %}} +**To review 1.x users with admin privileges**, run the following against your InfluxDB 1.x instance: + +```sql +SHOW USERS +``` + +Users with `admin` set to `true` will **not** be migrated. + +**To review the specific privileges granted to each 1.x user**, run the following for each user in your InfluxDB 1.x instance: + +```sql +SHOW GRANTS FOR "" +``` + +If no grants appear, the user will **not** be migrated. +{{% /expand %}} +{{< /expand-wrapper >}} + +If using an admin user for visualization or Chronograf administrative functions, +**create a new read-only user before upgrading**: + +##### Create a read-only 1.x user +```sh +> CREATE USER WITH PASSWORD '' +> GRANT READ ON TO "" +``` + +InfluxDB {{< current-version >}} only grants admin privileges to the primary user set up during the InfluxDB {{< current-version >}} upgrade. +This provides you with the opportunity to reassess who to grant admin permissions when setting up InfluxDB {{< current-version >}}. + +### Dashboards + +You can continue to use your existing dashboards and visualization tools with InfluxDB {{< current-version >}} via the [1.x read compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). +The upgrade process creates [DBRP mappings](/influxdb/v2.1/reference/api/influxdb-1x/dbrp/) to ensure existing users can execute InfluxQL queries with the appropriate permissions. + +However, if your dashboard tool is configured using a user with admin permissions, +you will need to create a new read-only user with the appropriate database permissions *before* upgrading. +This new username and password combination should be used within the data source configurations to continue to provide read-only access to the underlying data. + +Ensure your dashboards are all functioning before upgrading. + +### Other data + +The 1.x `_internal` database is not migrated with the `influxd upgrade` command. +To collect, store, and monitor similar internal InfluxDB metrics, +[create an InfluxDB {{< current-version >}} scraper](/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/create-a-scraper/) +to scrape data from the `/metrics` endpoint and store them in a bucket. + +### Secure by default + +InfluxDB {{< current-version >}} requires authentication and does not support the InfluxDB 1.x `auth-enabled = false` configuration option. + +Before upgrading to {{< current-version >}}, [enable authentication in your InfluxDB 1.x instance](/influxdb/v1.8/administration/authentication_and_authorization/#set-up-authentication) +and test your credentials to ensure your applications, agents, and visualization tools can connect to InfluxDB. + +If you upgrade with `auth-enabled = false`, the upgrade may appear complete, +but client requests to InfluxDB {{< current-version >}} may be silently ignored (you won't see a notification the request was denied). + +### In-memory indexing option + +InfluxDB {{< current-version >}} doesn't support [in-memory (`inmem`) indexing](/influxdb/v1.8/administration/config/#in-memory-inmem-index-settings). The following InfluxDB 1.x configuration options associated with `inmem` indexing are ignored in the upgrade process: + +- `max-series-per-database` +- `max-values-per-tag` + +### Interactive shell + +The InfluxDB 2.x `influx` CLI does not include an interactive shell for executing InfluxQL queries or Flux queries. For information about executing InfluxQL queries, see [Query data with InfluxQL](/influxdb/v2.1/query-data/influxql/). To build an interactive shell to execute Flux queries, [compile and build a command line Flux REPL from source](https://github.com/influxdata/flux/blob/master/README.md#getting-started). + +## Perform the upgrade + +If you've considered the [guidance above](#before-you-begin-important-considerations) +and are ready to proceed, follow these steps to upgrade your InfluxDB 1.x to InfluxDB {{< current-version >}}. + +1. [Download InfluxDB OSS {{< current-version >}}](https://portal.influxdata.com/downloads/). + Unpackage the InfluxDB binaries and place them in your `$PATH`. +2. Stop your running InfluxDB 1.x instance. + Make a backup copy of all 1.x data before upgrading: + + ```sh + cp -R .influxdb/ .influxdb_bak/ + ``` +3. Use `influxd version` to ensure you are running InfluxDB {{< current-version >}} from the command line. + The `influxd upgrade` command is only available in InfluxDB {{< current-version >}}. +4. If your 1.x configuration file is at the [default location](/influxdb/v1.8/administration/config/#using-the-configuration-file), run: + ```sh + influxd upgrade + ``` + {{% note %}} +#### Upgrade `.deb` packages +When installed from a `.deb` package, InfluxDB 1.x and 2.x run under the `influxdb` user. +If you've installed both versions from `.deb` packages, run the upgrade command +as the `influxdb` user: + +```sh +sudo -u influxdb influxd upgrade +``` + {{% /note %}} + If your 1.x configuration file is not at the default location, run: + + ```sh + influxd upgrade --config-file + ``` + + To store the upgraded {{< current-version >}} configuration file in a custom location, include the `--v2-config-path` flag: + + ```sh + influxd upgrade --v2-config-path + ``` + + +5. Follow the prompts to set up a new InfluxDB {{< current-version >}} instance. + + ``` + Welcome to InfluxDB {{< current-version >}} upgrade! + Please type your primary username: + + Please type your password: + + Please type your password again: + + Please type your primary organization name: + + Please type your primary bucket name: + + Please type your retention period in hours. + Or press ENTER for infinite: + + You have entered: + Username: + Organization: + Bucket: + Retention Period: infinite + Confirm? (y/n): y + ``` + +The output of the upgrade prints to standard output. +It is also saved (for troubleshooting and debugging) in the current directory to a file called `upgrade.log` located in the home directory of the user running `influxdb upgrade`. + +## Post-upgrade + +### Verify 1.x users were migrated to {{< current-version >}} + +To verify 1.x users were successfully migrated to {{< current-version >}}, run +[`influx v1 auth list`](/influxdb/v2.1/reference/cli/influx/v1/auth/list/). + +#### Add authorizations for external clients + +If your InfluxDB 1.x instance **did not have authentication enabled** and the +`influx v1 auth list` doesn't return any users, external clients connected to +your 1.x instance will not be able to access InfluxDB {{< current-version >}}, which requires authentication. + +**For these external clients to work with InfluxDB {{< current-version >}}:** + +1. [Manually create a 1.x-compatible authorization](/influxdb/v2.1/upgrade/v1-to-v2/manual-upgrade/#create-a-1x-compatible-authorization). +2. Update the client configuration to use the username and password associated + with your 1.x-compatible authorization. diff --git a/content/influxdb/v2.1/upgrade/v1-to-v2/docker.md b/content/influxdb/v2.1/upgrade/v1-to-v2/docker.md new file mode 100644 index 0000000000..d96292cdca --- /dev/null +++ b/content/influxdb/v2.1/upgrade/v1-to-v2/docker.md @@ -0,0 +1,251 @@ +--- +title: Upgrade from InfluxDB 1.x to 2.1 with Docker +list_title: Upgrade from 1.x to 2.1 with Docker +description: > + Use the automated upgrade process built into the InfluxDB 2.x Docker image to + update InfluxDB 1.x Docker deployments to InfluxDB 2.x. +menu: + influxdb_2_1: + parent: InfluxDB 1.x to 2.1 + name: Upgrade with Docker +weight: 101 +--- + +Use the automated upgrade process built into the [InfluxDB 2.x Docker image](https://hub.docker.com/_/influxdb) +to update InfluxDB 1.x Docker deployments to InfluxDB 2.x. + +- [Upgrade requirements](#upgrade-requirements) +- [Minimal upgrade](#minimal-upgrade) +- [Upgrade with a custom InfluxDB 1.x configuration file](#upgrade-with-a-custom-influxdb-1-x-configuration-file) +- [Upgrade with custom paths](#upgrade-with-custom-paths) + +{{% note %}} +#### Export continuous queries before upgrading +The automated upgrade process **does not** migrate InfluxDB 1.x continuous queries (CQs) +to InfluxDB 2.x tasks (the 2.x equivalent). Export all of your CQs before upgrading to InfluxDB 2.x. +For information about exporting and migrating CQs to tasks, see +[Migrate continuous queries to tasks](/influxdb/v2.1/upgrade/v1-to-v2/migrate-cqs/). +{{% /note %}} + +## Upgrade requirements +InfluxDB 2.x provides a 1.x compatibility API, but expects a different storage layout on disk. +To account for theses differences, the InfluxDB Docker image migrates +1.x data and into 2.x-compatible data automatically before booting the `influxd` server. + +- [InfluxDB 2.x initialization credentials](#influxdb-2x-initialization-credentials) +- [File system mounts](#file-system-mounts) +- [Upgrade initialization mode](#upgrade-initialization-mode) + +{{% note %}} +To ensure InfluxDB reboots post-upgrade without overwriting migrated data, +the upgrade won't run if an existing boltdb file is found at the +[configured 2.x configuration path](#file-system-mounts). +{{% /note %}} + +Find more information about the automated InfluxDB upgrade process, +see [Automatically upgrade from InfluxDB 1.x to {{< current-version >}}](/influxdb/v2.1/upgrade/v1-to-v2/automatic-upgrade/). + +### InfluxDB 2.x initialization credentials +The automated InfluxDB upgrade process bootstraps an initial admin user, +[organization](/influxdb/v2.1/reference/glossary/#organization), and +[bucket](/influxdb/v2.1/reference/glossary/#bucket) required by InfluxDB 2.x. +Set the following [environment variables in your Docker container](https://docs.docker.com/search/?q=environment%20variables) +to provide setup credentials: + +- `DOCKER_INFLUXDB_INIT_USERNAME`: Username to set for the admin user ({{< req >}}). +- `DOCKER_INFLUXDB_INIT_PASSWORD`: Password to set for the admin user ({{< req >}}). +- `DOCKER_INFLUXDB_INIT_ORG`: Name to set for the initial organization ({{< req >}}). +- `DOCKER_INFLUXDB_INIT_BUCKET`: Name to set for the initial bucket ({{< req >}}). +- `DOCKER_INFLUXDB_INIT_RETENTION`: Duration for the initial bucket's retention period. + If not set, the initial bucket will retain data forever. +- `DOCKER_INFLUXDB_INIT_ADMIN_TOKEN`: API token to associate with the admin user. + If not set, InfluxDB automatically generates a token. + +### File system mounts +The InfluxDB upgrade process requires extra volumes to be mounted into the 2.x container. +Use **environment variables** and **Docker mounts** to specify and configure the +appropriate mount paths for the following: + +- 1.x data on disk +- Custom 1.x configuration file (if any) +- 2.x data on disk (`/var/lib/influxdb2`) +- 2.x configuration directory (`/etc/influxdb2`) + +The InfluxDB upgrade process searches for mounted 1.x data and configuration files +in the following priority order: + +1. 1.x configuration file specified by the `DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG` environment variable +2. 1.x data directory specified by the `DOCKER_INFLUXDB_INIT_UPGRADE_V1_DIR` environment variable +3. 1.x configuration file mounted at `/etc/influxdb/influxdb.conf` +4. 1.x data directory mounted at `/var/lib/influxdb` + +{{% note %}} +#### Avoid data loss +By default, the automated upgrade process generates both data and configuration files +under `/var/lib/influxdb2` and `/etc/influxdb2`. +We recommend mounting volumes at both paths to avoid losing data. +{{% /note %}} + +### Upgrade initialization mode +Set the `DOCKER_INFLUXDB_INIT_MODE` environment variable to `upgrade`. + +## Minimal upgrade +If you're currently running a minimal InfluxDB 1.x deployment similar to: + +```sh +docker run -p 8086:8086 \ + -v influxdb:/var/lib/influxdb \ + influxdb:1.8 +``` + +**To upgrade this minimal deployment to InfluxDB 2.x:** + +1. Stop the running InfluxDB 1.x container. +2. Start the InfluxDB container with the following: + + - Volume mount for the InfluxDB 1.x data directory + - Volume mount for the InfluxDB 2.x data directory + - InfluxDB [initialization mode](#upgrade-initialization-mode) environment variable + - InfluxDB [initialization credential](#influxdb-2x-initialization-credentials) environment variables + - `influxdb:{{< current-version >}}` Docker image + + ```sh + docker run -p 8086:8086 \ + -v influxdb:/var/lib/influxdb \ + -v influxdb2:/var/lib/influxdb2 \ + -e DOCKER_INFLUXDB_INIT_MODE=upgrade \ + -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \ + -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \ + -e DOCKER_INFLUXDB_INIT_ORG=my-org \ + -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \ + influxdb:{{< current-version >}} + ``` + +## Upgrade with a custom InfluxDB 1.x configuration file +If you're currently running an InfluxDB 1.x deployment with a custom configuration +file similar to: + +```sh +docker run -p 8086:8086 \ + -v influxdb:/var/lib/influxdb \ + -v $PWD/influxdb.conf:/etc/influxdb/influxdb.conf:ro \ + influxdb:1.8 +``` + +**To upgrade an InfluxDB 1.x deployment with a custom configuration file to InfluxDB 2.x:** + +1. Stop the running InfluxDB 1.x container. +2. Start the InfluxDB container with the following: + + - Volume mount for the InfluxDB 1.x data directory + - Volume mount for the InfluxDB 1.x configuration file + - Volume mount for the InfluxDB 2.x data directory (`/var/lib/influxdb2`) + - Volume mount for the InfluxDB 2.x configuration directory (`/etc/influxdb2`) + - InfluxDB [initialization mode](#upgrade-initialization-mode) environment variable + - InfluxDB [initialization credential](#influxdb-2x-initialization-credentials) environment variables + - `influxdb:{{< current-version >}}` Docker image + +```sh +docker run -p 8086:8086 \ + -v influxdb:/var/lib/influxdb \ + -v $PWD/influxdb.conf:/etc/influxdb/influxdb.conf:ro \ + -v influxdb2:/var/lib/influxdb2 \ + -v influxdb2:/etc/influxdb2 \ + -e DOCKER_INFLUXDB_INIT_MODE=upgrade \ + -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \ + -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \ + -e DOCKER_INFLUXDB_INIT_ORG=my-org \ + -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \ + influxdb:{{< current-version >}} +``` + +## Upgrade with custom paths +If you're currently running an InfluxDB 1.x deployment with the data directory and +configuration file mounted at custom paths similar to: + +```sh +docker run -p 8086:8086 \ + -v influxdb:/root/influxdb/data \ + -v $PWD/influxdb.conf:/root/influxdb/influxdb.conf:ro \ + influxdb:1.8 -config /root/influxdb/influxdb.conf +``` + +**To upgrade an InfluxDB 1.x deployment with custom paths to InfluxDB 2.x:** + +1. Stop the running InfluxDB 1.x container. +2. Decide to either **keep using custom paths** or **use InfluxDB 2.x default paths**. + +{{< tabs-wrapper >}} +{{% tabs %}} +[Keep using custom paths](#) +[Use InfluxDB 2.x defaults](#) +{{% /tabs %}} + +{{% tab-content %}} + +To retain your custom InfluxDB 1.x paths, start the InfluxDB container with the following: + +- Volume mount for the InfluxDB 1.x data directory +- Volume mount for the InfluxDB 1.x configuration file +- Volume mount for the InfluxDB 2.x data directory +- Volume mount for the InfluxDB 2.x configuration directory +- InfluxDB [initialization mode](#upgrade-initialization-mode) environment variable +- InfluxDB [initialization credential](#influxdb-2x-initialization-credentials) environment variables +- InfluxDB 2.x [v1 configuration file path](#file-system-mounts) environment variable: + - `DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG` +- InfluxDB 1.x custom path environment variables: + - `INFLUXD_CONFIG_PATH` + - `INFLUXD_BOLT_PATH` + - `INFLUXD_ENGINE_PATH` +- `influxdb:{{< current-version >}}` Docker image + +```sh +docker run -p 8086:8086 \ + -v influxdb:/root/influxdb/data \ + -v $PWD/influxdb.conf:/root/influxdb/influxdb.conf:ro \ + -v influxdb2:/root/influxdb2/data \ + -v influxdb2:/root/influxdb2 \ + -e DOCKER_INFLUXDB_INIT_MODE=upgrade \ + -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \ + -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \ + -e DOCKER_INFLUXDB_INIT_ORG=my-org \ + -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \ + -e DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG=/root/influxdb/influxdb.conf \ + -e INFLUXD_CONFIG_PATH=/root/influxdb2/config.toml \ + -e INFLUXD_BOLT_PATH=/root/influxdb2/influxdb.bolt \ + -e INFLUXD_ENGINE_PATH=/root/influxdb2/engine \ + influxdb:{{< current-version >}} +``` +{{% /tab-content %}} + + +{{% tab-content %}} +To use default InfluxDB 2.x paths, start the InfluxDB container with the following: + +- Volume mount for the InfluxDB 1.x data directory +- Volume mount for the InfluxDB 1.x configuration file +- Volume mount for the InfluxDB 2.x data directory (`/var/lib/influxdb2`) +- Volume mount for the InfluxDB 2.x configuration directory (`/etc/influxdb2`) +- InfluxDB [initialization mode](#upgrade-initialization-mode) environment variable +- InfluxDB [initialization credential](#influxdb-2x-initialization-credentials) environment variables +- InfluxDB 2.x [v1 configuration file path](#file-system-mounts) environment variable: + - `DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG` +- `influxdb:{{< current-version >}}` Docker image + +```sh +docker run -p 8086:8086 \ + -v influxdb:/root/influxdb/data \ + -v $PWD/influxdb.conf:/root/influxdb/influxdb.conf:ro \ + -v influxdb2:/var/lib/influxdb2 \ + -v influxdb2:/etc/influxdb2 \ + -e DOCKER_INFLUXDB_INIT_MODE=upgrade \ + -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \ + -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \ + -e DOCKER_INFLUXDB_INIT_ORG=my-org \ + -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \ + -e DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG=/root/influxdb/influxdb.conf \ + influxdb:{{< current-version >}} +``` +{{% /tab-content %}} + +{{< /tabs-wrapper >}} diff --git a/content/influxdb/v2.1/upgrade/v1-to-v2/manual-upgrade.md b/content/influxdb/v2.1/upgrade/v1-to-v2/manual-upgrade.md new file mode 100644 index 0000000000..2a062fce57 --- /dev/null +++ b/content/influxdb/v2.1/upgrade/v1-to-v2/manual-upgrade.md @@ -0,0 +1,339 @@ +--- +title: Manually upgrade from InfluxDB 1.x to 2.1 +list_title: Manually upgrade from 1.x to 2.1 +description: > + To manually upgrade from InfluxDB 1.x to InfluxDB 2.1, migrate data, create + 1.x-compatible authorizations, and create database and retention policy + (DBRP) mappings. +menu: + influxdb_2_1: + parent: InfluxDB 1.x to 2.1 + name: Manually upgrade +weight: 11 +related: + - /influxdb/v2.1/upgrade/v1-to-v2/ + - /influxdb/v2.1/upgrade/v1-to-v2/migrate-cqs/ +--- + +To manually upgrade from InfluxDB 1.x to InfluxDB {{< current-version >}}: + +1. [Install InfluxDB {{< current-version >}}](#install-influxdb-21) +2. [Migrate custom configuration settings](#migrate-custom-configuration-settings) +3. [Create DBRP mappings](#create-dbrp-mappings) +4. [Create authorizations](#create-authorizations) +5. [Migrate time series data](#migrate-time-series-data) +6. [Migrate continuous queries](#migrate-continuous-queries) + +## Install InfluxDB {{< current-version >}} +[Download, install, and set up InfluxDB {{< current-version >}}](/influxdb/v2.1/get-started/). + +{{% note %}} +#### Required 2.x credentials +All InfluxDB {{< current-version >}} `influx` CLI examples below assume the required **host**, +**organization**, and **API token** credentials are provided by your +[`influx` CLI configuration](/influxdb/v2.1/reference/cli/influx/#provide-required-authentication-credentials). +{{% /note %}} + +## Migrate custom configuration settings +If you're using custom configuration settings in your InfluxDB 1.x instance, do the following: + +1. Compare 1.x and {{< current-version >}} configuration settings: + + {{< expand-wrapper >}} + {{% expand "View configuration option parity" %}} + +| 1.x configuration option | {{< current-version >}} configuration option | +| :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | +| **[data]** | | +| dir | [engine-path](/influxdb/v2.1/reference/config-options/#engine-path) | +| wal-dir | [engine-path](/influxdb/v2.1/reference/config-options/#engine-path) | +| wal-fsync-delay | [storage-wal-fsync-delay](/influxdb/v2.1/reference/config-options/#storage-wal-fsync-delay) | +| index-version | | +| trace-logging-enabled | | +| query-log-enabled | | +| strict-error-handling | | +| validate-keys | [storage-validate-keys](/influxdb/v2.1/reference/config-options/#storage-validate-keys) | +| cache-max-memory-size | [storage-cache-max-memory-size](/influxdb/v2.1/reference/config-options/#storage-cache-max-memory-size) | +| cache-snapshot-memory-size | [storage-cache-snapshot-memory-size](/influxdb/v2.1/reference/config-options/#storage-cache-snapshot-memory-size) | +| cache-snapshot-write-cold-duration | [storage-cache-snapshot-write-cold-duration](/influxdb/v2.1/reference/config-options/#storage-cache-snapshot-write-cold-duration) | +| compact-full-write-cold-duration | [storage-compact-full-write-cold-duration](/influxdb/v2.1/reference/config-options/#storage-compact-full-write-cold-duration) | +| max-concurrent-compactions | [storage-max-concurrent-compactions](/influxdb/v2.1/reference/config-options/#storage-max-concurrent-compactions) | +| compact-throughput | | +| compact-throughput-burst | [storage-compact-throughput-burst](/influxdb/v2.1/reference/config-options/#storage-compact-throughput-burst) | +| tsm-use-madv-willneed | [storage-tsm-use-madv-willneed](/influxdb/v2.1/reference/config-options/#storage-tsm-use-madv-willneed) | +| max-series-per-database | | +| max-values-per-tag | | +| max-index-log-file-size | [storage-max-index-log-file-size](/influxdb/v2.1/reference/config-options/#storage-max-index-log-file-size) | +| series-id-set-cache-size | [storage-series-id-set-cache-size](/influxdb/v2.1/reference/config-options/#storage-series-id-set-cache-size) | +| | | +| **[retention]** | | +| check-interval | [storage-retention-check-interval](/influxdb/v2.1/reference/config-options/#storage-retention-check-interval) | +| | | +| **[shard-precreation]** | | +| check-interval | [storage-shard-precreator-check-interval](/influxdb/v2.1/reference/config-options/#storage-shard-precreator-check-interval) | +| advance-period | [storage-shard-precreator-advance-period](/influxdb/v2.1/reference/config-options/#storage-shard-precreator-advance-period) | +| | | +| **[http]** | | +| flux-enabled | | +| flux-log-enabled | | +| bind-address | [http-bind-address](/influxdb/v2.1/reference/config-options/#http-bind-address) | +| auth-enabled | | +| realm | | +| log-enabled | | +| suppress-write-log | | +| access-log-path | | +| access-log-status-filters | | +| write-tracing | | +| pprof-enabled | [pprof-disabled](/influxdb/v2.1/reference/config-options/#pprof-disabled) | +| pprof-auth-enabled | | +| debug-pprof-enabled | | +| ping-auth-enabled | | +| https-enabled | | +| https-certificate | [tls-cert](/influxdb/v2.1/reference/config-options/#tls-cert) | +| https-private-key | [tls-key](/influxdb/v2.1/reference/config-options/#tls-key) | +| shared-secret | | +| max-row-limit | | +| max-connection-limit | | +| unix-socket-enabled | | +| bind-socket | | +| max-body-size | | +| max-concurrent-write-limit | | +| max-enqueued-write-limit | | +| enqueued-write-timeout | [http-write-timeout](/influxdb/v2.1/reference/config-options/#http-write-timeout) | +| | | +| **[logging]** | | +| format | | +| level | [log-level](/influxdb/v2.1/reference/config-options/#log-level) | +| suppress-logo | | +| | | +| **[tls]** | | +| ciphers | [tls-strict-ciphers](/influxdb/v2.1/reference/config-options/#tls-strict-ciphers) | +| min-version | [tls-min-version](/influxdb/v2.1/reference/config-options/#tls-min-version) | +| max-version | | + +{{% note %}} +#### 1.x configuration groups not in {{< current-version >}} +The following 1.x configuration groups **do not** apply to InfluxDB {{< current-version >}}: + +- meta +- coordinator +- monitor +- subscriber +- graphite +- collectd +- opentsdb +- udp +- continuous_queries +{{% /note %}} + {{% /expand %}} + {{< /expand-wrapper >}} + +2. Apply your 1.x custom settings to the comparable InfluxDB {{< current-version >}} settings using + `influxd` flags, environment variables, or a {{< current-version >}} configuration file. + For more information about configuring InfluxDB {{< current-version >}}, see + [Configuration options](/influxdb/v2.1/reference/config-options/). +3. **Restart `influxd`**. + +## Create DBRP mappings +InfluxDB database and retention policy (DBRP) mappings associate database and +retention policy combinations with InfluxDB {{< current-version >}} [buckets](/influxdb/v2.1/reference/glossary/#bucket). +These mappings allow InfluxDB 1.x clients to successfully query and write to +InfluxDB {{< current-version >}} buckets while using the 1.x DBRP convention. + +_For more information about DBRP mapping, see +[Database and retention policy mapping](/influxdb/v2.1/reference/api/influxdb-1x/dbrp/)._ + +**To map a DBRP combination to an InfluxDB {{< current-version >}} bucket:** + +1. **Create a bucket** + [Create an InfluxDB {{< current-version >}} bucket](/influxdb/v2.1/organizations/buckets/create-bucket/). + We recommend creating a bucket for each unique 1.x database and retention + policy combination using the following naming convention: + + ```sh + # Naming convention + db-name/rp-name + + # Example + telegraf/autogen + ``` + +2. **Create a DBRP mapping** + Use the [`influx v1 dbrp create` command](/influxdb/v2.1/reference/cli/influx/v1/dbrp/create/) + to create a DBRP mapping. + Provide the following: + + - database name + - retention policy name _(not retention period)_ + - [bucket ID](/influxdb/v2.1/organizations/buckets/view-buckets/) + - _(optional)_ `--default` flag if you want the retention policy to be the default retention + policy for the specified database + + {{< code-tabs-wrapper >}} + {{% code-tabs %}} +[DB with one RP](#) +[DB with multiple RPs](#) + {{% /code-tabs %}} + {{% code-tab-content %}} +```sh +influx v1 dbrp create \ + --db example-db \ + --rp example-rp \ + --bucket-id 00xX00o0X001 \ + --default +``` + {{% /code-tab-content %}} + {{% code-tab-content %}} +```sh +# Create telegraf/autogen DBRP mapping with autogen +# as the default RP for the telegraf DB + +influx v1 dbrp create \ + --db telegraf \ + --rp autogen \ + --bucket-id 00xX00o0X001 \ + --default + +# Create telegraf/downsampled-daily DBRP mapping that +# writes to a different bucket + +influx v1 dbrp create \ + --db telegraf \ + --rp downsampled-daily \ + --bucket-id 00xX00o0X002 +``` + {{% /code-tab-content %}} + {{< /code-tabs-wrapper >}} + +3. **Confirm the DBRP mapping was created** + Use the [`influx v1 dbrp list`](/influxdb/v2.1/reference/cli/influx/v1/dbrp/list/) to list existing DBRP mappings. + + ```sh + influx v1 dbrp list + ``` + +For information about managing DBRP mappings, see the +[`influx v1 dbrp` command documentation](/influxdb/v2.1/reference/cli/influx/v1/dbrp/). + +## Create authorizations +InfluxDB {{< current-version >}} requires authentication and provides two authentication methods: + +- [Token authentication](#token-authentication) +- [1.x compatible authorizations](#1x-compatible-authorizations) + +### Token authentication +Use [InfluxDB {{< current-version >}} token authentication](/influxdb/v2.1/security/tokens/) to +authenticate requests to InfluxDB {{< current-version >}}. + +##### Recommended if: +- Your 1.x instance **does not have authentication enabled**. + +{{% note %}} +#### Use tokens with basic authentication +To use tokens with InfluxDB clients that require an InfluxDB username and password, +provide an arbitrary user name and pass the token as the password. +{{% /note %}} + +### 1.x-compatible authorizations +InfluxDB {{< current-version >}} provides a [1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/) +that lets you authenticate using a username and password as in InfluxDB 1.x. +If authentication is enabled in your InfluxDB 1.x instance, +[create a 1.x-compatible authorization](#create-a-1x-compatible-authorization) +with the same username and password as your InfluxDB 1.x instance to allow +external clients to connect to your InfluxDB {{< current-version >}} instance without any change. + +##### Recommended if: +- Your 1.x instance **has authentication enabled**. +- You're using **InfluxDB 1.x clients or client libraries** configured with + InfluxDB usernames and passwords. + +{{% note %}} +1.x compatibility authorizations are separate from credentials used to log +into the InfluxDB {{< current-version >}} user interface (UI). +{{% /note %}} + +#### Create a 1.x-compatible authorization +Use the InfluxDB {{< current-version >}} [`influx v1 auth create` command](/influxdb/v2.1/reference/cli/influx/v1/auth/create/) +to create a 1.x-compatible authorization that grants read/write permissions to specific {{< current-version >}} buckets. +Provide the following: + +- list of [bucket IDs](/influxdb/v2.1/organizations/buckets/view-buckets/) to + grant read or write permissions to +- new v1 auth username +- new v1 auth password _(when prompted)_ + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Single bucket](#) +[Mutiple buckets](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +influx v1 auth create \ + --read-bucket 00xX00o0X001 \ + --write-bucket 00xX00o0X001 \ + --username example-user +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sh +influx v1 auth create \ + --read-bucket 00xX00o0X001 \ + --read-bucket 00xX00o0X002 \ + --write-bucket 00xX00o0X001 \ + --write-bucket 00xX00o0X002 \ + --username example-user +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +For information about managing 1.x compatible authorizations, see the +[`influx v1 auth` command documentation](/influxdb/v2.1/reference/cli/influx/v1/auth/). + +## Migrate time series data +To migrate time series data from your InfluxDB 1.x instance to InfluxDB {{< current-version >}}: + +1. Use the **InfluxDB 1.x** [`influx_inspect export` command](/{{< latest "influxdb" "v1" >}}/tools/influx_inspect/#export) + to export time series data as line protocol. + Include the `-lponly` flag to exclude comments and the data definition + language (DDL) from the output file. + + _We recommend exporting each DBRP combination separately to easily write data + to a corresponding InfluxDB {{< current-version >}} bucket._ + + ```sh + # Syntax + influx_inspect export \ + -database \ + -retention \ + -out \ + -lponly + + # Example + influx_inspect export \ + -database example-db \ + -retention example-rp \ + -out /path/to/example-db_example-rp.lp \ + -lponly + ``` + +2. Use the **InfluxDB {{< current-version >}}** [`influx write` command](/influxdb/v2.1/reference/cli/influx/write/) + to write the exported line protocol to InfluxDB {{< current-version >}}. + + ```sh + # Syntax + influx write \ + --bucket \ + --file + + # Example + influx write \ + --bucket example-db/example-rp \ + --file /path/to/example-db_example-rp.lp + ``` + +3. Repeat steps 1-2 for each bucket. + +## Migrate continuous queries +For information about migrating InfluxDB 1.x continuous queries to InfluxDB {{< current-version >}} tasks, +see [Migrate continuous queries to tasks](/influxdb/v2.1/upgrade/v1-to-v2/migrate-cqs/). diff --git a/content/influxdb/v2.1/upgrade/v1-to-v2/migrate-cqs.md b/content/influxdb/v2.1/upgrade/v1-to-v2/migrate-cqs.md new file mode 100644 index 0000000000..06cd09a047 --- /dev/null +++ b/content/influxdb/v2.1/upgrade/v1-to-v2/migrate-cqs.md @@ -0,0 +1,381 @@ +--- +title: Migrate continuous queries to tasks +description: > + InfluxDB OSS 2.x replaces 1.x continuous queries (CQs) with **InfluxDB tasks**. + To migrate continuous queries to InfluxDB 2.x, convert InfluxDB 1.x CQs into Flux and create new + InfluxDB 2.x tasks. +menu: + influxdb_2_1: + parent: InfluxDB 1.x to 2.1 + name: Migrate CQs +weight: 102 +related: + - /influxdb/v2.1/query-data/get-started/ + - /influxdb/v2.1/query-data/flux/ + - /influxdb/v2.1/process-data/ + - /influxdb/v2.1/process-data/common-tasks/ + - /influxdb/v2.1/reference/flux/flux-vs-influxql/ +--- + +InfluxDB OSS {{< current-version >}} replaces 1.x continuous queries (CQs) with **InfluxDB tasks**. +To migrate continuous queries to InfluxDB {{< current-version >}} tasks, do the following: + +1. [Output all InfluxDB 1.x continuous queries](#output-all-influxdb-1x-continuous-queries) +2. [Convert continuous queries to Flux queries](#convert-continuous-queries-to-flux-queries) +3. [Create new InfluxDB tasks](#create-new-influxdb-tasks) + +## Output all InfluxDB 1.x continuous queries + +If using the `influxd upgrade` command, by default, all continuous queries are +output to `~/continuous_queries.txt` during the upgrade process. +To customize the destination path of the continuous queries file, +use the `--continuous-query-export-path` flag with the `influxd upgrade` command. + +```sh +influxd upgrade --continuous-query-export-path /path/to/continuous_queries.txt +``` + +**To manually output continuous queries:** + +1. Use the **InfluxDB 1.x `influx` interactive shell** to run `SHOW CONTINUOUS QUERIES`: + + {{< keep-url >}} + ```sh + $ influx + Connected to http://localhost:8086 version {{< latest-patch version="1.8" >}} + InfluxDB shell version: {{< latest-patch version="1.8" >}} + > SHOW CONTINUOUS QUERIES + ``` + +2. Copy and save the displayed continuous queries. + +## Convert continuous queries to Flux queries + +To migrate InfluxDB 1.x continuous queries to InfluxDB {{< current-version >}} tasks, convert the InfluxQL query syntax to Flux. +The majority of continuous queries are simple downsampling queries and can be converted quickly +using the [`aggregateWindow()` function](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow/). +For example: + +##### Example continuous query +```sql +CREATE CONTINUOUS QUERY "downsample-daily" ON "my-db" +BEGIN + SELECT mean("example-field") + INTO "my-db"."example-rp"."average-example-measurement" + FROM "example-measurement" + GROUP BY time(1h) +END +``` + +##### Equivalent Flux task +```js +option task = { + name: "downsample-daily", + every: 1d +} + +from(bucket: "my-db/") + |> range(start: -task.every) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> filter(fn: (r) => r._field == "example-field") + |> aggregateWindow(every: 1h, fn: mean) + |> set(key: "_measurement", value: "average-example-measurement") + |> to( + org: "example-org", + bucket: "my-db/example-rp" + ) +``` + +### Convert InfluxQL continuous queries to Flux +Review the following statements and clauses to see how to convert your CQs to Flux: + +- [ON clause](#on-clause) +- [SELECT statement](#select-statement) +- [INTO clause](#into-clause) +- [FROM clause](#from-clause) +- [AS clause](#as-clause) +- [WHERE clause](#where-clause) +- [GROUP BY clause](#group-by-clause) +- [RESAMPLE clause](#resample-clause) + +#### ON clause +The `ON` clause defines the database to query. +In InfluxDB OSS {{< current-version >}}, database and retention policy combinations are mapped to specific buckets +(for more information, see [Database and retention policy mapping](/influxdb/v2.1/reference/api/influxdb-1x/dbrp/)). + +Use the [`from()` function](/{{< latest "flux" >}}/stdlib/universe/from) +to specify the bucket to query: + +###### InfluxQL +```sql +CREATE CONTINUOUS QUERY "downsample-daily" ON "my-db" +-- ... +``` + +###### Flux +```js +from(bucket: "my-db/") +// ... +``` + +#### SELECT statement +The `SELECT` statement queries data by field, tag, and time from a specific measurement. +`SELECT` statements can take many different forms and converting them to Flux depends +on your use case. For information about Flux and InfluxQL function parity, see +[Flux vs InfluxQL](/influxdb/v2.1/reference/syntax/flux/flux-vs-influxql/#influxql-and-flux-parity). +See [other resources available to help](#other-helpful-resources). + +#### INTO clause +The `INTO` clause defines the measurement to write results to. +`INTO` also supports fully-qualified measurements that include the database and retention policy. +In InfluxDB OSS {{< current-version >}}, database and retention policy combinations are mapped to specific buckets +(for more information, see [Database and retention policy mapping](/influxdb/v2.1/reference/api/influxdb-1x/dbrp/)). + +To write to a measurement different than the measurement queried, use +[`set()`](/{{< latest "flux" >}}/stdlib/universe/set/) or +[`map()`](/{{< latest "flux" >}}/stdlib/universe/map/) +to change the measurement name. +Use the `to()` function to specify the bucket to write results to. + +###### InfluxQL +```sql +-- ... +INTO "example-db"."example-rp"."example-measurement" +-- ... +``` + +###### Flux +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[set()](#) +[map()](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```js +// ... + |> set(key: "_measurement", value: "example-measurement") + |> to(bucket: "example-db/example-rp") +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```js +// ... + |> map(fn: (r) => ({ r with _measurement: "example-measurement"})) + |> to(bucket: "example-db/example-rp") +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +##### Write pivoted data to InfluxDB +InfluxDB 1.x query results include a column for each field. +InfluxDB {{< current-version >}} does not do this by default, but it is possible with +[`pivot()`](/{{< latest "flux" >}}/stdlib/universe/pivot) +or [`schema.fieldsAsCols()`](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/fieldsascols/). + +If you use `to()` to write _pivoted data_ back to InfluxDB {{< current-version >}}, each field column is stored as a tag. +To write pivoted fields back to InfluxDB as fields, import the `experimental` package +and use the [`experimental.to()` function](/{{< latest "flux" >}}/stdlib/experimental/to/). + +###### InfluxQL +```sql +CREATE CONTINUOUS QUERY "downsample-daily" ON "my-db" +BEGIN + SELECT mean("example-field-1"), mean("example-field-2") + INTO "example-db"."example-rp"."example-measurement" + FROM "example-measurement" + GROUP BY time(1h) +END +``` + +###### Flux +```js +// ... + +from(bucket: "my-db/") + |> range(start: -task.every) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> filter(fn: (r) => r._field == "example-field-1" or r._field == "example-field-2") + |> aggregateWindow(every: task.every, fn: mean) + |> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") + |> experimental.to(bucket: "example-db/example-rp") +``` + +#### FROM clause +The from clause defines the measurement to query. +Use the [`filter()` function](/{{< latest "flux" >}}/stdlib/universe/filter/) +to specify the measurement to query. + +###### InfluxQL +```sql +-- ... +FROM "example-measurement" +-- ... +``` + +###### Flux +```js +// ... + |> filter(fn: (r) => r._measurement == "example-measurement") +``` + +#### AS clause +The `AS` clause changes the name of the field when writing data back to InfluxDB. +Use [`set()`](/{{< latest "flux" >}}/stdlib/universe/set/) +or [`map()`](/{{< latest "flux" >}}/stdlib/universe/map/) +to change the field name. + +###### InfluxQL +```sql +-- ... +AS newfield +-- ... +``` + +###### Flux +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[set()](#) +[map()](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```js +// ... + |> set(key: "_field", value: "newfield") +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```js +// ... + |> map(fn: (r) => ({ r with _field: "newfield"})) +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +#### WHERE clause +The `WHERE` clause uses predicate logic to filter results based on fields, tags, or timestamps. +Use the [`filter()` function](/{{< latest "flux" >}}/stdlib/universe/filter/) +and Flux [comparison operators](/{{< latest "flux" >}}/spec/operators/#comparison-operators) +to filter results based on fields and tags. +Use the [`range()` function](/{{< latest "flux" >}}/stdlib/universe/range/) to filter results based on timestamps. + +###### InfluxQL +```sql +-- ... +WHERE "example-tag" = "foo" AND time > now() - 7d +``` + +###### Flux +```js +// ... + |> range(start: -7d) + |> filter(fn: (r) => r["example-tag"] == "foo") +``` + +#### GROUP BY clause +The InfluxQL `GROUP BY` clause groups data by specific tags or by time (typically to calculate an aggregate value for windows of time). + +##### Group by tags +Use the [`group()` function](/{{< latest "flux" >}}/stdlib/universe/group/) +to modify the [group key](/{{< latest "flux" >}}/get-started/data-model/#group-key) and change how data is grouped. + +###### InfluxQL +```sql +-- ... +GROUP BY "location" +``` + +###### Flux +```js +// ... + |> group(columns: ["location"]) +``` + +##### Group by time +Use the [`aggregateWindow()` function](//{{< latest "flux" >}}/stdlib/universe/aggregatewindow/) +to group data into time windows and perform an aggregation on each window. +In CQs, the interval specified in the `GROUP BY time()` clause determines the CQ execution interval. +Use the `GROUP BY time()` interval to set the `every` task option. + +###### InfluxQL +```sql +-- ... +SELECT MEAN("example-field") +FROM "example-measurement" +GROUP BY time(1h) +``` + +###### Flux +```js +option task = { + name: "task-name", + every: 1h +} + +// ... + |> filter(fn: (r) => + r._measurement == "example-measurement" and + r._field == "example-field" + ) + |> aggregateWindow(every: task.every, fn: mean) +``` + +#### RESAMPLE clause + +The CQ `RESAMPLE` clause uses data from the last specified duration to calculate a new aggregate point. +The `EVERY` interval in `RESAMPLE` defines how often the CQ runs. +The `FOR` interval defines the total time range queried by the CQ. + +To accomplish this same functionality in a Flux task, set the `start` parameter +in the `range()` function to the negative `FOR` duration. +Define the task execution interval in the `task` options. +For example: + +###### InfluxQL +```sql +CREATE CONTINUOUS QUERY "resample-example" ON "my-db" +RESAMPLE EVERY 1m FOR 30m +BEGIN + SELECT exponential_moving_average(mean("example-field"), 30) + INTO "resample-average-example-measurement" + FROM "example-measurement" + WHERE region = 'example-region' + GROUP BY time(1m) +END +``` + +###### Flux +```js +option task = { + name: "resample-example", + every: 1m +} + +from(bucket: "my-db/") + |> range(start: -30m) + |> filter(fn: (r) => + r._measurement == "example-measurement" and + r._field == "example-field" and + r.region == "example-region" + ) + |> aggregateWindow(every: 1m, fn: mean) + |> exponentialMovingAverage(n: 30) + |> set(key: "_measurement", value: "resample-average-example-measurement") + |> to(bucket: "my-db/") +``` + +## Create new InfluxDB tasks +After converting your continuous query to Flux, use the Flux query to +[create a new task](/influxdb/v2.1/process-data/manage-tasks/create-task/). + +## Other helpful resources +The following resources are available and may be helpful when converting +continuous queries to Flux tasks. + +##### Documentation +- [Get started with Flux](/{{< latest "flux" >}}/get-started/) +- [Query data with Flux](/influxdb/v2.1/query-data/flux/) +- [Common tasks](/influxdb/v2.1/process-data/common-tasks/#downsample-data-with-influxdb) + +##### Community +- Post in the [InfluxData Community](https://community.influxdata.com/) +- Ask in the [InfluxDB Community Slack](https://influxdata.com/slack) diff --git a/content/influxdb/v2.1/upgrade/v2-to-v2.md b/content/influxdb/v2.1/upgrade/v2-to-v2.md new file mode 100644 index 0000000000..0003b29ae3 --- /dev/null +++ b/content/influxdb/v2.1/upgrade/v2-to-v2.md @@ -0,0 +1,81 @@ +--- +title: Upgrade from InfluxDB 2.x to InfluxDB 2.1 +description: > + To upgrade from InfluxDB 2.0 beta 16 or earlier to InfluxDB 2.1 (stable), + manually upgrade all resources and data to the latest version by completing these steps. +menu: + influxdb_2_1: + parent: Upgrade InfluxDB + name: InfluxDB 2.x to 2.1 +weight: 10 +related: + - /influxdb/v2.1/reference/cli/influxd/downgrade/ + - /influxdb/v2.1/install/ +--- + +Upgrade to InfluxDB {{< current-version >}} from an earlier version of InfluxDB 2.x. + +{{% note %}} +#### InfluxDB 2.0 beta-16 or earlier +If you're upgrading from InfluxDB 2.0 beta-16 or earlier, you must first +[upgrade to InfluxDB 2.0](/influxdb/v2.0/upgrade/v2-beta-to-v2/), +and then complete the steps below. +{{% /note %}} + +{{< tabs-wrapper >}} +{{% tabs %}} +[macOS](#) +[Linux](#) +[Windows](#) +[Docker](#) +{{% /tabs %}} + + +{{% tab-content %}} +Do one of the following: + +- [Use homebrew to upgrade](#use-homebrew-to-upgrade) +- [Manually upgrade](#manually-upgrade) + +### Use homebrew to upgrade +``` +brew upgrade influxdb +``` + +### Manually upgrade +To manually upgrade, [download and install the latest version of InfluxDB {{< current-version >}} for macOS](/influxdb/v2.1/install/#manually-download-and-install) +in place of your current 2.x version. +{{% /tab-content %}} + + + +{{% tab-content %}} + +[Download and install the latest version of InfluxDB {{< current-version >}} for Linux](/influxdb/v2.1/install/?t=Linux#download-and-install-influxdb-v21) +in place of current 2.x version. + +{{% /tab-content %}} + + + +{{% tab-content %}} + +[Download and install the latest version of InfluxDB {{< current-version >}} for Windows](/influxdb/v2.1/install/?t=Windows) +in place of current 2.x version. + +{{% /tab-content %}} + + + +{{% tab-content %}} + +To upgrade to InfluxDB {{< current-version >}} with Docker, update your Docker +image to use the latest InfluxDB image. + +```sh +influxdb:{{< latest-patch >}} +``` +{{% /tab-content %}} + + +{{< /tabs-wrapper >}} diff --git a/content/influxdb/v2.1/users/_index.md b/content/influxdb/v2.1/users/_index.md new file mode 100644 index 0000000000..0c08404d74 --- /dev/null +++ b/content/influxdb/v2.1/users/_index.md @@ -0,0 +1,26 @@ +--- +title: Manage users +seotitle: Manage users in InfluxDB +description: Manage users in InfluxDB using the InfluxDB UI or the influx CLI. +influxdb/v2.1/tags: [users, authentication] +menu: + influxdb_2_1: + name: Manage users +weight: 11 +products: [oss] +--- + +Users are those with access to InfluxDB. +To grant a user permission to access data, add them as a [member of an organization](/influxdb/v2.1/organizations/members/) +and provide them with an [API token](/influxdb/v2.1/security/tokens/). + +The following articles walk through managing users. + +{{% note %}} +#### InfluxDB 2.x/1.x compatibility +If you [upgraded from 1.x to {{< current-version >}}](/influxdb/v2.1/upgrade/v1-to-v2/), +use the [`influx v1 auth`](/influxdb/v2.1/reference/cli/influx/v1/auth/) commands +to manage authorizations for the InfluxDB [1.x compatibility API](/influxdb/v2.1/reference/api/influxdb-1x/). +{{% /note %}} + +{{< children >}} diff --git a/content/influxdb/v2.1/users/change-password.md b/content/influxdb/v2.1/users/change-password.md new file mode 100644 index 0000000000..ee365c64b6 --- /dev/null +++ b/content/influxdb/v2.1/users/change-password.md @@ -0,0 +1,35 @@ +--- +title: Change your password +seotitle: Change your password in InfluxDB +description: Change your password in InfluxDB using the influx CLI. +menu: + influxdb_2_1: + name: Change your password + parent: Manage users +weight: 105 +--- + +Use `influx` command line interface (CLI) to update your password. + +{{% note %}} +User passwords cannot be updated in the InfluxDB UI. +{{% /note %}} + +## Change your password using the influx CLI + +Use the [`influx user password` command](/influxdb/v2.1/reference/cli/influx/user/password) +to update a password for a user. To update a password, you need the following: + +- Username or user ID _(provided in the output of `influx user list`)_ +- New password + +##### Update a password +```sh +# Syntax +influx user password -n + +# Example +influx user password -n johndoe +``` + +When prompted, enter and confirm the new password. diff --git a/content/influxdb/v2.1/users/create-user.md b/content/influxdb/v2.1/users/create-user.md new file mode 100644 index 0000000000..89d987efa2 --- /dev/null +++ b/content/influxdb/v2.1/users/create-user.md @@ -0,0 +1,51 @@ +--- +title: Create a user +seotitle: Create a user in InfluxDB +description: Create a user in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_2_1: + name: Create a user + parent: Manage users +weight: 101 +products: [oss] +--- + +Use the `influx` command line interface (CLI) to create a user. + +{{% note %}} +Additional users cannot be created in the InfluxDB UI. +{{% /note %}} + +## Create a user using the influx CLI + +To create a new user, use the [`influx user create` command](/influxdb/v2.1/reference/cli/influx/user/create) +and include the following: + +- Username +- Organization name or organization ID to add the user to _(provided in the output of + [`influx org list`](/influxdb/v2.1/reference/cli/influx/org/list/))_ + +```sh +# Syntax +influx user create -n -o + +# Example +influx user create -n johndoe -o example-org +``` + +### Create a user with a password and organization +To create a new user with a password and add the user as a member of an organization, +include a password and organization ID with the `influx user create` command. + +- Username +- Organization name or organization ID to add the user to _(provided in the output of + [`influx org list`](/influxdb/v2.1/reference/cli/influx/org/list/))_ +- Password + +```sh +# Syntax +influx user create -n -p -o + +# Example +influx user create -n johndoe -p PaSsWoRd -o example-org +``` diff --git a/content/influxdb/v2.1/users/delete-user.md b/content/influxdb/v2.1/users/delete-user.md new file mode 100644 index 0000000000..be156170bd --- /dev/null +++ b/content/influxdb/v2.1/users/delete-user.md @@ -0,0 +1,41 @@ +--- +title: Delete a user +seotitle: Delete a user from InfluxDB +description: Delete a user from InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_2_1: + name: Delete a user + parent: Manage users +weight: 103 +products: [oss] +--- + +Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) +to delete a user. + +{{% warn %}} +Deleting a user removes them completely from InfluxDB. +To remove a user from an organization without deleting the user entirely, see +[Remove a member from an organization](/influxdb/v2.1/organizations/members/remove-member/). +{{% /warn %}} + +## Delete a user from the InfluxDB UI + +{{% note %}} +Users cannot be deleted from the InfluxDB UI. +{{% /note %}} + +## Delete a user using the influx CLI + +Use the [`influx user delete` command](/influxdb/v2.1/reference/cli/influx/user/delete) +to delete a user. Deleting a user requires the following: + +- The user ID _(provided in the output of `influx user list`)_ + +```sh +# Syntax +influx user delete -i + +# Example +influx user delete -i 034ad714fdd6f000 +``` diff --git a/content/influxdb/v2.1/users/update-user.md b/content/influxdb/v2.1/users/update-user.md new file mode 100644 index 0000000000..2db0bf8f9f --- /dev/null +++ b/content/influxdb/v2.1/users/update-user.md @@ -0,0 +1,36 @@ +--- +title: Update a user +seotitle: Update a user in InfluxDB +description: Update a user in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_2_1: + name: Update a user + parent: Manage users +weight: 103 +products: [oss] +--- + +Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) +to update a user. + +## Update a user in the InfluxDB UI + +{{% note %}} +User information cannot be updated in the InfluxDB UI. +{{% /note %}} + +## Update a user using the influx CLI + +Use the [`influx user update` command](/influxdb/v2.1/reference/cli/influx/user/update) +to update a user. Updating a user requires the following: + +- The user ID _(provided in the output of `influx user list`)_ + +##### Update the name of a user +```sh +# Syntax +influx user update -i -n + +# Example +influx user update -i 034ad714fdd6f000 -n janedoe +``` diff --git a/content/influxdb/v2.1/users/view-users.md b/content/influxdb/v2.1/users/view-users.md new file mode 100644 index 0000000000..182a2f452a --- /dev/null +++ b/content/influxdb/v2.1/users/view-users.md @@ -0,0 +1,33 @@ +--- +title: View users +seotitle: View users in InfluxDB +description: Review a list of users in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_2_1: + name: View users + parent: Manage users +weight: 102 +products: [oss] +--- + +Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) +to view users. + +## View users in the InfluxDB UI + +{{% note %}} +There is no list of users in the InfluxDB UI. +{{% /note %}} + +## View users using the influx CLI + +Use the [`influx user list` command](/influxdb/v2.1/reference/cli/influx/user/list) +to view users. + +```sh +influx user list +``` + +Filtering options such as filtering by username or ID are available. +See the [`influx user list` documentation](/influxdb/v2.1/reference/cli/influx/user/list) +for information about other available flags. diff --git a/content/influxdb/v2.1/visualize-data/_index.md b/content/influxdb/v2.1/visualize-data/_index.md new file mode 100644 index 0000000000..da9eb67893 --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/_index.md @@ -0,0 +1,16 @@ +--- +title: Visualize data with the InfluxDB UI +description: > + InfluxDB offers a complete dashboard solution for visualizing your time series data. + Create custom dashboards with flexible queries and visualization types. +influxdb/v2.1/tags: [visualize] +menu: + influxdb_2_1: + name: Visualize data +weight: 5 +--- + +The InfluxDB user interface (UI) provides tools for building custom dashboards to visualize your data. +The following articles outline ways to customize and manage dashboards. + +{{< children >}} diff --git a/content/influxdb/v2.1/visualize-data/annotations.md b/content/influxdb/v2.1/visualize-data/annotations.md new file mode 100644 index 0000000000..c6550b1090 --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/annotations.md @@ -0,0 +1,68 @@ +--- +title: Use annotations in dashboards +description: > + Add annotations to your InfluxDB dashboards to provide useful, contextual information about single points in time. +influxdb/v2.1/tags: [labels, annotations] +menu: + influxdb_2_1: + name: Use annotations + parent: Visualize data +weight: 105 +--- + +Add annotations to your dashboards to provide useful, contextual information about single points in time. After an annotation is created, edit the annotation by updating the text or timestamp, or delete the annotation. + +- [Create an annotation](#create-an-annotation) +- [Edit an annotation](#edit-an-annotation) +- [View or hide annotations](#view-or-hide-annotations) +- [Delete an annotation](#delete-an-annotation) + +{{% note %}} +Annotations may be useful to highlight operations or anomalies for your team to reference. +{{% /note %}} + + + +## Create an annotation + +1. In the navigation menu on the left, select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} + +2. Select an existing dashboard to add the annotation to, or [create a new dashboard](/influxdb/cloud/visualize-data/dashboards/create-dashboard/), and then click the **Annotations** button. +3. In a dashboard cell, do one of the following: + - Press Shift and click the graph at the time you want to annotate. + - To add an annotation to a time range, press Shift, click the start time, and then drag your cursor to the end time. +4. On the **Add Annotation** page: + + 1. Verify the time or time range, and update if needed. + 2. Enter a message (maximum of 255 characters) to associate with the selected time or time range. + 3. Click **Save Annotation**. The annotation appears in the cell (dotted lines indicate the selected time or time range). + +## Edit an annotation + +1. In the navigation menu on the left, select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} + +2. Open the dashboard with the annotation to edit, and then click the annotation to open it. +3. Update the text (maximum of 255 characters) or timestamp, and then click **Save Annotation**. + +## View or hide annotations + +By default, annotations are visible. + +1. In the navigation menu on the left, select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} + +2. Open a dashboard with annotations: + - To hide annotations, click the **Annotations** button. The button is gray when annotations are hidden. + - To show annotations, click the **Annotations** button. The button is purple when annotations are visible. + +## Delete an annotation + +1. In the navigation menu on the left, select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} +2. Open a dashboard with the annotation to delete, click the dotted annotation line, and then click **Delete Annotation**. diff --git a/content/influxdb/v2.1/visualize-data/dashboards/_index.md b/content/influxdb/v2.1/visualize-data/dashboards/_index.md new file mode 100644 index 0000000000..790289ae36 --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/dashboards/_index.md @@ -0,0 +1,37 @@ +--- +title: Manage InfluxDB dashboards +description: Create, edit, and manage custom dashboards in the InfluxDB user interface (UI). +influxdb/v2.1/tags: [dashboards] +menu: + influxdb_2_1: + name: Manage dashboards + parent: Visualize data +weight: 102 +--- + +Create, edit, and manage dashboards from the **Dashboards** tab in the left navigation. + +{{< children >}} + + +## View your dashboard ID + +Use the InfluxDB UI or `influx` CLI to view your dashboard ID. + +### Dashboard ID in the UI + +When viewing a dashboard in the InfluxDB UI, your dashboard ID appears in the URL. + +
    +http://localhost:8086/orgs/03a2bbf46249a000/dashboards/04b6b15034cc000/...
+
    + +### Dashboard ID in the CLI +Use [`influx dashboards`](/influxdb/v2.1/reference/cli/influx/dashboards/) to view a list of dashboards and IDs. + +```sh +> influx dashboards +ID Name +03a2bbf46249a000 dashboard-1 +03ace3a859669000 dashboard-2 +``` diff --git a/content/influxdb/v2.1/visualize-data/dashboards/control-dashboard.md b/content/influxdb/v2.1/visualize-data/dashboards/control-dashboard.md new file mode 100644 index 0000000000..1eb788d4ff --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/dashboards/control-dashboard.md @@ -0,0 +1,67 @@ +--- +title: Control a dashboard +seotitle: Control an InfluxDB dashboard +description: Control an InfluxDB dashboard in the InfluxDB user interface (UI). +influxdb/v2.1/tags: [dashboards] +menu: + influxdb_2_1: + name: Control a dashboard + parent: Manage dashboards +weight: 203 +--- + +## Control at the dashboard level + +Use dashboard controls in the upper left to update your dashboard. + +### Add a cell + +Click **{{< icon "add-cell" >}} Add Cell** to open the Data Explorer and configure a new cell for your dashboard. + +For details on using the Data Explorer, see [Explore metrics](/influxdb/v2.1/visualize-data/explore-metrics/). + +### Add a note + +1. Click **{{< icon "note" >}} Add Note** to add a note cell to your dashboard. +2. Enter your note in Markdown in the left pane. A preview appears in the right pane. +3. Enable the **Show note when query returns no data** option to show the note only when the query displays no data. +4. Click **Save**. + +### Select timezone + +Click the timezone dropdown to select a timezone to use for the dashboard. Select either the local time (default) or UTC. + +{{< img-hd src="/img/influxdb/2-0-controls-timezone.png" alt="Select timezone" />}} + +### Manually refresh dashboard + +Click the refresh button (**{{< icon "refresh" >}}**) to manually refresh the dashboard's data. + +#### Manually refresh a single dashboard cell + +1. Click the **{{< icon "gear" >}}** on the dashboard cell you want to refresh. +2. Click **{{< icon "refresh" >}} Refresh**. + +### Select time range + +1. Select from the time range options in the dropdown menu. + + {{< img-hd src="/img/influxdb/2-0-controls-time-range.png" alt="Select time range" />}} + +2. Select **Custom Time Range** to enter a custom time range with precision up to nanoseconds. +The default time range is 5 minutes. + + > The custom time range uses the selected timezone (local time or UTC). + +### Add variables + +Click **Variables** to display variables available for your dashboard. For details, see [Use and manage variables](/influxdb/v2.1/visualize-data/variables/) + +### Presentation mode + +Click the fullscreen icon (**{{< icon "fullscreen" >}}**) to enter presentation mode. Presentation mode allows you to view [a dashboard] in full screen, hiding the left and top navigation menus so only the cells appear. This mode might be helpful, for example, for stationary screens dedicated to monitoring visualizations. + +### Toggle dark mode and light mode +Click the moon or sun icons to toggle your dashboard between **dark mode** and **light mode.** + +{{< img-hd src="/img/influxdb/2-0-controls-dark-light-mode.png" alt="Dark & light mode"/>}} diff --git a/content/influxdb/v2.1/visualize-data/dashboards/create-dashboard.md b/content/influxdb/v2.1/visualize-data/dashboards/create-dashboard.md new file mode 100644 index 0000000000..0b7c11fe80 --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/dashboards/create-dashboard.md @@ -0,0 +1,58 @@ +--- +title: Create a dashboard +seotitle: Create an InfluxDB dashboard +description: > + Create a new dashboard or import an existing dashboard in the + InfluxDB user interface (UI). +influxdb/v2.1/tags: [dashboards] +menu: + influxdb_2_1: + name: Create a dashboard + parent: Manage dashboards +weight: 201 +--- + +## Create a new dashboard + +1. In the navigation menu on the left, select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} + +2. Click the **{{< icon "plus" >}} Create Dashboard** menu in the upper right and select **New Dashboard**. +3. Enter a name for your dashboard in the **Name this dashboard** field in the upper left. + + +**To import an existing dashboard**: + +1. In the navigation menu on the left, select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} + +2. Click the **Create Dashboard** menu in the upper right and select **Import Dashboard**. +3. In the window that appears: + - Select **Upload File** to drag-and-drop or select a file. + - Select **Paste JSON** to paste in JSON. +4. Click **Import JSON as Dashboard**. + +## Clone a dashboard + +1. In the navigation menu on the left, select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} + +2. Hover over the dashboard and click **{{< icon "copy" >}}**. +3. Click **Clone**. The cloned dashboard opens. + +#### Add data to your dashboard + +1. From your dashboard, click **{{< icon "add-cell" >}} Add Cell**. +2. Create a query in the Data Explorer following the instructions in [Explore metrics](/influxdb/v2.1/visualize-data/explore-metrics). +3. Enter a name for your cell in the upper left. +4. Click the checkmark icon (**{{< icon "checkmark" >}}**) to save the cell to your dashboard. + You can also send data to your dashboard directly from the Data Explorer. For details, [Explore metrics](/influxdb/v2.1/visualize-data/explore-metrics). + +#### Add a note to your dashboard +1. From your dashboard, click **{{< icon "note" >}} Add Note** in the upper left. +2. Enter your note in the window that appears. You can use Markdown syntax to format your note. +3. To preview your Markdown formatting, click the **Preview** option. +4. Click **Save**. diff --git a/content/influxdb/v2.1/visualize-data/dashboards/delete-dashboard.md b/content/influxdb/v2.1/visualize-data/dashboards/delete-dashboard.md new file mode 100644 index 0000000000..074cd07ae5 --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/dashboards/delete-dashboard.md @@ -0,0 +1,23 @@ +--- +title: Delete a dashboard +seotitle: Delete an InfluxDB dashboard +description: Delete a dashboard from the InfluxDB user interface (UI). +influxdb/v2.1/tags: [dashboards] +menu: + influxdb_2_1: + parent: Manage dashboards +weight: 204 +--- + +To delete a dashboard from the InfluxDB user interface (UI): + +1. In the navigation menu on the left, select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} + +2. Hover over the dashboard in the list of dashboards and click **{{< icon "trash" >}}**. +3. Click **Delete**. + +{{% warn %}} +Deleting a dashboard cannot be undone. +{{% /warn %}} diff --git a/content/influxdb/v2.1/visualize-data/dashboards/export-dashboard.md b/content/influxdb/v2.1/visualize-data/dashboards/export-dashboard.md new file mode 100644 index 0000000000..38ab186390 --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/dashboards/export-dashboard.md @@ -0,0 +1,26 @@ +--- +title: Export a dashboard +seotitle: Export an InfluxDB dashboard +description: > + Export a dashboard using the InfluxDB user interface (UI). +influxdb/v2.1/tags: [dashboards] +menu: + influxdb_2_1: + name: Export a dashboard + parent: Manage dashboards +weight: 203 +--- + +InfluxDB lets you export dashboards from the InfluxDB user interface (UI). + +1. In the navigation menu on the left, select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} + +2. Hover over a dashboard and click the gear icon (**{{< icon "gear" >}}**), + and then select **Export**. +3. Review the JSON in the window that appears. +4. Select one of the following options: + * **Download JSON**: Download the dashboard as a JSON file. + * **Save as template**: Save the JSON as a dashboard template. + * **Copy to Clipboard**: Copy the JSON to your clipboard. diff --git a/content/influxdb/v2.1/visualize-data/labels.md b/content/influxdb/v2.1/visualize-data/labels.md new file mode 100644 index 0000000000..930f2006a9 --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/labels.md @@ -0,0 +1,44 @@ +--- +title: Manage labels in the InfluxDB UI +description: > + Labels are a way to add visual metadata to dashboards, tasks, and other items + in the InfluxDB UI. View and manage labels in the InfluxDB user interface. +influxdb/v2.1/tags: [labels] +menu: + influxdb_2_1: + name: Manage labels + parent: Visualize data +weight: 104 +--- + +Labels are a way to add visual metadata to dashboards, tasks, and other items in the InfluxDB UI. +To manage labels: + +- In the navigation menu on the left, select **Settings** > **Labels**. + + {{< nav-icon "settings" >}} + + +#### Create a label +1. Click **{{< icon "plus" >}} Create Label**. +2. Enter a **Name** for the label. +3. Enter a description for the label _(Optional)_. +4. Select a **Color** for the label. +5. Click **Create Label**. + +#### Edit a label +1. In the label list view, click the name of the label you would like to edit. + The **Edit Label** overlay will appear. +2. Make the desired changes to the label. +3. Click **Save Changes**. + +#### Delete a label +1. In the label list view, hover over the label you would like to delete and click **{{< icon "trash" >}}**. +2. Click **Delete**. + +### Add labels to dashboard items +1. In the list view of dashboards, tasks, or other assets, hover over the item to which you would like to add a label. +2. Click the {{< icon "add-label" >}} icon that appears below the name. + The **Add Labels** overlay will appear. +3. Type the name of the label you would like to add to filter the list of available labels. + Click the label you would like to add. diff --git a/content/influxdb/v2.1/visualize-data/variables/_index.md b/content/influxdb/v2.1/visualize-data/variables/_index.md new file mode 100644 index 0000000000..7733db8fc0 --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/variables/_index.md @@ -0,0 +1,73 @@ +--- +title: Use and manage variables +seotitle: Use and manage dashboard variables +description: > + Dashboard variables allow you to alter specific components of cells' queries + without having to edit the queries, making it easy to interact with your dashboard cells and explore your data. +menu: + influxdb_2_1: + parent: Visualize data +weight: 103 +influxdb/v2.1/tags: [variables] +--- + +Dashboard variables let you alter specific components of cells' queries without having to edit the queries, +making it easy to interact with your dashboard cells and explore your data. + +Variables are scoped by organization. + +## Use dashboard variables +Both [predefined dashboard variables](#predefined-dashboard-variables) and [custom dashboard variables](#custom-dashboard-variables) +are stored in a `v` record associated with each dashboard. +Reference each variable using dot-notation (e.g. `v.variableName`). + +```js +from(bucket: v.bucket) + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => r._measurement == v.measurement and r._field == v.field) + |> aggregateWindow(every: v.windowPeriod, fn: mean) +``` + +When building Flux queries for dashboard cells, view available dashboard variables +in the **Variables** tab next to the Functions tab. + +{{< img-hd src="/img/influxdb/2-0-variables-data-explorer-view.png" />}} + +Click a variable name to add it to your query and select a value from the **Value** dropdown. + +## Link to dashboards with variables defined in the URL + +When you apply a variable to your dashboard, `&vars[variable_name]=value` is appended to the URL so you can share the link with the variables included. + +## Predefined dashboard variables +The InfluxDB user interface (UI) provides the following predefined dashboard variables: + +#### v.timeRangeStart +Specifies the beginning of the queried time range. +This variable is typically used to define the [`start` parameter](/{{< latest "flux" >}}/stdlib/universe/range#start) +of the `range()` function. + +The **Time Range** selector defines the value of this variable. + +#### v.timeRangeStop +Specifies the end of the queried time range. +This variable is typically used to define the [`stop` parameter](/{{< latest "flux" >}}/stdlib/universe/range#stop) +of the `range()` function. + +The **Time Range** selector defines the value of this variable. +It defaults to `now`. + +#### v.windowPeriod +Specifies the period of windowed data. +This variable is typically used to define the `every` or `period` parameters of the +[`window()` function](/{{< latest "flux" >}}/stdlib/universe/window) +in data aggregation operations. + +The value of this variable is calculated by analyzing the duration of the Flux +query it is used within. Queries that fetch data from a longer time range will +have a larger `v.windowPeriod` duration. + +## Custom dashboard variables +Create, manage, and use custom dashboard variables in the InfluxDB user interface (UI). + +{{< children >}} diff --git a/content/influxdb/v2.1/visualize-data/variables/common-variables.md b/content/influxdb/v2.1/visualize-data/variables/common-variables.md new file mode 100644 index 0000000000..34347f6150 --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/variables/common-variables.md @@ -0,0 +1,112 @@ +--- +title: Common variable queries +description: Useful queries to use to populate values in common dashboard variable use cases. +menu: + influxdb_2_1: + parent: Use and manage variables + name: Common variable queries +weight: 208 +influxdb/v2.1/tags: [variables] +--- + +## List buckets +List all buckets in the current organization. + +_**Flux functions:** +[buckets()](/{{< latest "flux" >}}/stdlib/universe/buckets/), +[rename()](/{{< latest "flux" >}}/stdlib/universe/rename/), +[keep()](/{{< latest "flux" >}}/stdlib/universe/keep/)_ + +```js +buckets() + |> rename(columns: {"name": "_value"}) + |> keep(columns: ["_value"]) +``` + +## List measurements +List all measurements in a specified bucket. + +_**Flux package:** [InfluxDB schema](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/) +**Flux functions:** [schema.measurements()](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/measurements/)_ + +```js +import "influxdata/influxdb/schema" + +schema.measurements(bucket: "bucket-name") +``` + +## List fields in a measurement +List all fields in a specified bucket and measurement. + +_**Flux package:** [InfluxDB schema](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/) +**Flux functions:** [schema.measurementTagValues()](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/measurementtagvalues/)_ + +```js +import "influxdata/influxdb/schema" + +schema.measurementTagValues( + bucket: "bucket-name", + measurement: "measurement-name", + tag: "_field" +) +``` + +## List unique tag values +List all unique tag values for a specific tag in a specified bucket. +The example below lists all unique values of the `host` tag. + +_**Flux package:** [InfluxDB schema](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/)_ +_**Flux functions:** [schema.tagValues()](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/tagvalues/)_ + +```js +import "influxdata/influxdb/schema" + +schema.tagValues(bucket: "bucket-name", tag: "host") +``` + +## List Docker containers +List all Docker containers when using the Docker Telegraf plugin. + +_**Telegraf plugin:** [Docker](/{{< latest "telegraf" >}}/plugins/#docker)_ +_**Flux package:** [InfluxDB schema](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/)_ +_**Flux functions:** [schema.tagValues()](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/tagvalues/)_ + +```js +import "influxdata/influxdb/schema" + +schema.tagValues(bucket: "bucket-name", tag: "container_name") +``` + +## List Kubernetes pods +List all Kubernetes pods when using the Kubernetes Telegraf plugin. + +_**Telegraf plugin:** [Kubernetes](/{{< latest "telegraf" >}}/plugins/#kubernetes)_ +_**Flux package:** [InfluxDB schema](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/)_ +_**Flux functions:** [schema.measurementTagValues()](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/measurementtagvalues/)_ + +```js +import "influxdata/influxdb/schema" + +schema.measurementTagValues( + bucket: "bucket-name", + measurement: "kubernetes_pod_container", + tag: "pod_name" +) +``` + +## List Kubernetes nodes +List all Kubernetes nodes when using the Kubernetes Telegraf plugin. + +_**Telegraf plugin:** [Kubernetes](/{{< latest "telegraf" >}}/plugins/#kubernetes)_ +_**Flux package:** [InfluxDB schema](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/)_ +_**Flux functions:** [schema.measurementTagValues()](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/schema/measurementtagvalues/)_ + +```js +import "influxdata/influxdb/schema" + +schema.measurementTagValues( + bucket: "bucket-name", + measurement: "kubernetes_node", + tag: "node_name" +) +``` diff --git a/content/influxdb/v2.1/visualize-data/variables/create-variable.md b/content/influxdb/v2.1/visualize-data/variables/create-variable.md new file mode 100644 index 0000000000..f06b1ddd0c --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/variables/create-variable.md @@ -0,0 +1,73 @@ +--- +title: Create a variable +seotitle: Create a dashboard variable +description: Create dashboard variables in the Data Explorer, from the Organization page, or import a variable. +menu: + influxdb_2_1: + parent: Use and manage variables +weight: 201 +influxdb/v2.1/tags: [variables] +--- + +Create dashboard variables in the Data Explorer, from the Settings section, or import a variable. +**Variable names must be unique.** + +There are multiple variable types that provide different means of populating your list of variable values. +_For information about variable types, see [Variable types](/influxdb/v2.1/visualize-data/variables/variable-types/)._ + +{{% note %}} +##### Variable name restrictions +Variable names must begin with a letter or underscore (`_`). + +The following names cannot be used as dashboard variables because they are reserved keywords in Flux: +`and`, `import`, `not`, `return`, `option`, `test`, `empty`, `in`, `or`, `package`, and `builtin`. +{{% /note %}} + +## Create a variable in the Data Explorer + +{{% note %}} +InfluxData recommends using the Data Explorer to create +[Query dashboard variables](/influxdb/v2.1/visualize-data/variables/variable-types/#query). +The [Table visualization type](/influxdb/v2.1/visualize-data/visualization-types/table/) and +**View Raw Data** option to provide human-readable query results. +{{% /note %}} + +1. Click the **Data Explorer** icon in the sidebar. + + {{< nav-icon "data-explorer" >}} + +2. Use the **Query Builder** or **Script Editor** to build a query. +3. Use the [Table visualization type](/influxdb/v2.1/visualize-data/visualization-types/table/) + or enable the **View Raw Data** option to view human-readable query results. +4. Click **Save As** in the upper right. +5. In the window that appears, select **Variable**. +6. Enter a name for your variable in the **Name** field. +7. Click **Create**. + +_For information about common Query variables, see [Common variable queries](/influxdb/v2.1/visualize-data/variables/common-variables/)._ + +## Create a variable in the Settings section + +1. Click the **Settings** icon in the navigation bar. + + {{< nav-icon "settings" >}} + +2. Select the **Variables** tab. +3. Enter a name for your variable. +4. Select your variable type. For details on each type, see [Variable types](/influxdb/v2.1/visualize-data/variables/variable-types/). +5. Enter the appropriate variable information. +6. Click **Create**. + +## Import a variable +InfluxDB lets you import variables exported from InfluxDB in JSON format. + +1. Click the **Settings** icon in the navigation bar. + + {{< nav-icon "settings" >}} + +2. Select the **Variables** tab. +3. Click the **{{< icon "plus" >}} Create Variable** drop-down menu and select **Import Variable**. +4. In the window that appears: + - Select **Upload File** to drag and drop or select a file. + - Select **Paste JSON** to paste in JSON. +6. Click **Import JSON as Variable**. diff --git a/content/influxdb/v2.1/visualize-data/variables/delete-variable.md b/content/influxdb/v2.1/visualize-data/variables/delete-variable.md new file mode 100644 index 0000000000..2a22e2eeff --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/variables/delete-variable.md @@ -0,0 +1,26 @@ +--- +title: Delete a variable +seotitle: Delete a dashboard variable +description: Delete a dashboard variable in the InfluxDB user interface. +menu: + influxdb_2_1: + parent: Use and manage variables +weight: 205 +influxdb/v2.1/tags: [variables] +--- + +Delete an existing variable in the InfluxDB user interface (UI). + +### Delete a variable + +1. Click the **Settings** icon in the navigation bar. + + {{< nav-icon "settings" >}} + +2. Select the **Variables** tab. +3. Hover over a variable, click the **{{< icon "trash" >}}** icon, and **Delete**. + +{{% warn %}} +Once deleted, any dashboards with queries that utilize the variable will no +longer function correctly. +{{% /warn %}} diff --git a/content/influxdb/v2.1/visualize-data/variables/export-variable.md b/content/influxdb/v2.1/visualize-data/variables/export-variable.md new file mode 100644 index 0000000000..906cf23cd7 --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/variables/export-variable.md @@ -0,0 +1,27 @@ +--- +title: Export a variable +seotitle: Export a dashboard variable +description: Export a dashboard variable in the InfluxDB user interface. +menu: + influxdb_2_1: + parent: Use and manage variables +weight: 204 +influxdb/v2.1/tags: [variables] +--- +Export dashboard variables from the InfluxDB user interface (UI). +Variables are exported as downloadable JSON files. + +### Export a variable + +1. Click the **Settings** icon in the navigation bar. + + {{< nav-icon "settings" >}} + +2. Select the **Variables** tab. +3. Hover over a variable in the list, then click the gear icon (**{{< icon "gear" >}}**) + and select **Export**. +4. Review the JSON in the window that appears. +5. Select one of the following options: + * **Download JSON**: Download the dashboard as a JSON file. + * **Save as template**: Save the JSON as a dashboard template. + * **Copy to Clipboard**: Copy the JSON to your clipboard. diff --git a/content/influxdb/v2.1/visualize-data/variables/update-variable.md b/content/influxdb/v2.1/visualize-data/variables/update-variable.md new file mode 100644 index 0000000000..0e70c1cfb1 --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/variables/update-variable.md @@ -0,0 +1,23 @@ +--- +title: Update a variable +seotitle: Update a dashboard variable +description: Update a dashboard variable in the InfluxDB user interface. +menu: + influxdb_2_1: + parent: Use and manage variables +weight: 203 +influxdb/v2.1/tags: [variables] +--- + +Update an existing dashboard variable's name or JSON content in the InfluxDB user interface (UI). + +### Update a variable + +1. Click the **Settings** icon in the navigation bar. + + {{< nav-icon "settings" >}} + +2. Select the **Variables** tab. +3. Click a variable's name from the list. +4. Update the variable's name, type, and associated information. +5. Click **Submit**. diff --git a/content/influxdb/v2.1/visualize-data/variables/variable-types.md b/content/influxdb/v2.1/visualize-data/variables/variable-types.md new file mode 100644 index 0000000000..091594572f --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/variables/variable-types.md @@ -0,0 +1,97 @@ +--- +title: Variable types +seotitle: Dashboard variable types +description: Overview of the types of dashboard variables available in InfluxDB +menu: + influxdb_2_1: + parent: Use and manage variables +weight: 207 +influxdb/v2.1/tags: [variables] +--- + +Variable types determine how a variable's list of possible values is populated. +The following variable types are available: + +- [Map](#map) +- [Query](#query) +- [CSV](#csv) + +### Map +Map variables use a list of key value pairs in CSV format to map keys to specific values. +Keys populate the variable's value list in the InfluxDB user interface (UI), but +values are used when actually processing the query. + +The most common use case for map variables is aliasing simple, human-readable keys +to complex values. + +##### Map variable example +```js +Juanito MacNeil,"5TKl6l8i4idg15Fxxe4P" +Astrophel Chaudhary,"bDhZbuVj5RV94NcFXZPm" +Ochieng Benes,"YIhg6SoMKRUH8FMlHs3V" +Mila Emile,"o61AhpOGr5aO3cYVArC0" +``` + +### Query +Query variable values are populated using the `_value` column of a Flux query. + +##### Query variable example +```js +// List all buckets +buckets() + |> rename(columns: {"name": "_value"}) + |> keep(columns: ["_value"]) +``` + +_For examples of dashboard variable queries, see [Common variable queries](/influxdb/v2.1/visualize-data/variables/common-variables)._ + +{{% note %}} +#### Important things to note about variable queries +- The variable will only use values from the `_value` column. + If the data you’re looking for is in a column other than `_value`, use the + [`rename()`](/{{< latest "flux" >}}/stdlib/universe/rename/) or + [`map()`](/{{< latest "flux" >}}/stdlib/universe/map/) functions + to change the name of that column to `_value`. +- The variable will only use the first table in the output stream. + Use the [`group()` function](/{{< latest "flux" >}}/stdlib/universe/group) + to group everything into a single table. +- Do not use any [predefined dashboard variables](/influxdb/v2.1/visualize-data/variables/#predefined-dashboard-variables) in variable queries. +{{% /note %}} + +### CSV +CSV variables use a CSV-formatted list to populate variable values. +A common use case is when the list of potential values is static and cannot be +queried from InfluxDB. + +##### CSV variable examples +``` +value1, value2, value3, value4 +``` +``` +value1 +value2 +value3 +value4 +``` + +## Use custom dashboard variables + +Use the Flux `v` record and [dot or bracket notation](/{{< latest "flux" >}}/data-types/composite/record/#reference-values-in-a-record) to access custom dashboard variables. + +For example, to use a custom dashboard variable named `exampleVar` in a query, +reference the variable with `v.exampleVar`: + +```js +from(bucket: "telegraf") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => r._measurement == "cpu" ) + |> filter(fn: (r) => r._field == "usage_user" ) + |> filter(fn: (r) => r.cpu == v.exampleVar) +``` + +**To select variable values:** + +- **In a dashboard:** Use the dashboard variable drop-down menus at the top of your dashboard. +- **In the Script Editor:** Click the **Variables** tab on the right of the Script Editor, click the name of the variable, and then select the variable value from the drop-down menu. + +_For more on using dashboard variables, see [Use and manage variables](/influxdb/v2.1/visualize-data/variables/)._ diff --git a/content/influxdb/v2.1/visualize-data/variables/view-variables.md b/content/influxdb/v2.1/visualize-data/variables/view-variables.md new file mode 100644 index 0000000000..5b890c5452 --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/variables/view-variables.md @@ -0,0 +1,31 @@ +--- +title: View variables +seotitle: View dashboard variables +description: View dashboard variables in the InfluxDB user interface. +menu: + influxdb_2_1: + parent: Use and manage variables +weight: 203 +influxdb/v2.1/tags: [variables] +--- + +View a list of dashboard variables in the InfluxDB user interface (UI) from an organization or from the Data Explorer. + +## View variables in the organization + +1. Click the **Settings** icon in the navigation bar. + + {{< nav-icon "settings" >}} + +3. Select the **Variables** tab. + +## View variables in the Data Explorer + +1. Click the **Data Explorer** icon in the navigation bar. + + {{< nav-icon "data-explorer" >}} + +2. Switch to **Script Editor**. +3. Click the **Variables** tab to the right of the script editor. + + {{< img-hd src="/img/influxdb/2-0-variables-data-explorer-view.png" />}} diff --git a/content/influxdb/v2.1/visualize-data/visualization-types/_index.md b/content/influxdb/v2.1/visualize-data/visualization-types/_index.md new file mode 100644 index 0000000000..7bf2a9da2c --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/visualization-types/_index.md @@ -0,0 +1,17 @@ +--- +title: Visualization types +description: > + The InfluxDB UI provides multiple visualization types to visualize your data in + a format that makes the most sense for your use case. Use the available customization + options to customize each visualization. +menu: + influxdb_2_1: + parent: Visualize data +weight: 105 +--- + +The InfluxDB UI provides multiple visualization types to visualize your data in +a format that makes the most sense for your use case. Use the available customization +options to customize each visualization. + +{{< children >}} diff --git a/content/influxdb/v2.1/visualize-data/visualization-types/band.md b/content/influxdb/v2.1/visualize-data/visualization-types/band.md new file mode 100644 index 0000000000..3a2f19d509 --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/visualization-types/band.md @@ -0,0 +1,174 @@ +--- +title: Band visualization +list_title: Band +list_image: /img/influxdb/2-0-visualizations-Band-example.png +description: +weight: 201 +menu: + influxdb_2_1: + name: Band + parent: Visualization types +--- + +The **Band** visualization displays the upper and lower boundaries for groups of data over time. Boundaries are determined by applying aggregate functions to your data for a specified window period, and then setting the aggregate functions for a specified upper, main, or lower boundary. + +## Set up the Band visualization + +To see bands (boundaries) in the **Band Plot** visualization, you must set up two or three boundaries for comparison. + +### Set up the band visualization in the Data Explorer + +1. Click the **Data Explorer** icon in the navigation bar. + + {{< nav-icon "data-explorer" >}} + +2. Enter your query (see [Explore data with Flux and the Data Explorer](/influxdb/v2.1/visualize-data/explore-metrics/#explore-data-with-flux-and-the-data-explorer)). You must include the aggregate functions used to determine the Band Plot visualization boundaries in your query. +3. Select the **Band Plot** option from the visualization dropdown in the upper left, and then click **Customize**. +4. Under **Data**, select the following: + - For **X Column** and **Y Column**, select the columns to display for the x- and y- axes. + - For **Time Format**, select the timestamp format to display in the visualization. +5. Under **Aggregate Functions**, select a function to determine each boundary (column) for comparison (select two or three): + - In the **Upper Column Name** field, select a function for the upper boundary. + - In the **Main Column Name** field, select a function for the main boundary. + - In the **Lower Column Name** field, select a function for the lower boundary. +6. (Optional) Continue to customize your visualization, including options such as interpolation, color, hover dimension, and y-axis settings. For more information, see [Options](#options) and [Y Axis](#y-axis) below. + + **Tip:** If you do not see shaded boundaries in the **Band Plot** visualization, verify the query window period includes a sufficient number of data points for the selected aggregate function. By default, the window period is automatically set to ten seconds (`10s`). To adjust your window period, select **Custom**, and then enter a supported time unit (for example nanoseconds (`ns`), microseconds (`us`), milliseconds (`ms`), seconds (`s`), or hours (`h`). + +{{< img-hd src="/img/influxdb/2-0-visualizations-Band-example.png" alt="Band example" />}} + +### Set up the band plot visualization in the Script Editor + +1. Click the **Data Explorer** icon in the navigation bar. + + {{< nav-icon "data-explorer" >}} + +2. Click **Script Editor**. +3. Select the **Band Plot** option from the visualization dropdown in the upper left. +4. Create three aggregate functions: one for the main boundary, one for the upper boundary, and one for the lower boundary. The following example uses the [`mean()`](/{{< latest "flux" >}}/stdlib/universe/mean/), [`max()`](/{{< latest "flux" >}}/stdlib/universe/max/), and [`min()`](/{{< latest "flux" >}}/stdlib/universe/min) functions: + +```js +from(bucket: "bucket_1") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => r["_measurement"] == "cpu") + |> filter(fn: (r) => r["_field"] == "usage_system") + |> filter(fn: (r) => r["cpu"] == "cpu0" or r["cpu"] == "cpu1") + |> aggregateWindow(every: 15s, fn: mean, createEmpty: false) + |> yield(name: "mean") + +from(bucket: "bucket_1") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => r["_measurement"] == "cpu") + |> filter(fn: (r) => r["_field"] == "usage_system") + |> filter(fn: (r) => r["cpu"] == "cpu0" or r["cpu"] == "cpu1") + |> aggregateWindow(every: 15s, fn: max, createEmpty: false) + |> yield(name: "max") + +from(bucket: "bucket_1") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => r["_measurement"] == "cpu") + |> filter(fn: (r) => r["_field"] == "usage_system") + |> filter(fn: (r) => r["cpu"] == "cpu0" or r["cpu"] == "cpu1") + |> aggregateWindow(every: 15s, fn: min, createEmpty: false) + |> yield(name: "min") +``` + +5. (Optional) Customize the name of the yielded results for each function by editing the `name` parameter in the [`yield()`](/{{< latest "flux" >}}/stdlib/universe/yield/) function. +For example, to change the name of the first function from `mean` to `Average`, modify the last line to the following: + ```js + |> yield(name: "Average") + ``` +6. Click **Customize** in the upper left. +7. Under **Aggregate Functions**, enter the functions you created to determine each boundary (column) for comparison. If you changed the `yield` name for any of the functions above, enter the modified name here instead of the function name: + - In the **Upper Column Name** field, enter the result set to use for the upper boundary. + - In the **Main Column Name** field, enter the result set to use for the main boundary. + - In the **Lower Column Name** field, enter the function for the lower boundary. +7. (Optional) Continue to customize your visualization, including options such as interpolation, color, hover dimension, static legend, and y-axis settings. For more information, see [Options](#options) and [Y Axis](#y-axis) below. + +### Customize column names + +## Band behavior + +Like a line graph, the band visualization shows how values change over time. Additionally, it displays upper and lower "bands" for the measurements. + +For example, in the band chart above, the lines represent the mean `usage_system` values for the `cpu` measurement for `cpu0` and `cpu1`. The upper and lower limits of the bands are defined by the `max` and `min` aggregate functions, respectively. + +## Band controls + +To view **Band** controls, click **{{< icon "gear" >}} Customize** next to the visualization dropdown. + +###### Data + +- **X Column**: Select a column to display on the x-axis. +- **Y Column**: Select a column to display on the y-axis. +- **Time Format**: Select the time format. Options include: + {{< ui/timestamp-formats >}} + +###### Aggregate functions + +- **Upper Column Name**: Aggregate function to display for upper bounds of data. +- **Main Column Name**: Aggregate function to display for main graph line. +- **Lower Column Name**: Aggregate function to display for lower bounds of data. + +###### Options + +- **Interpolation**: + - **Linear**: Display a time series in a line graph. + - **Smooth**: Display a time series in a line graph with smooth point interpolation. + - **Step**: Display a time series in a staircase graph. +- **Line Colors**: Select a color scheme to use for your graph. +- **Hover Dimension**: Select the data to display in the tooltip when you hover over the graph: + - **auto** or **X-Axis**: Show all points with the same x value along the y-axis. + - **Y-Axis**: Show all points with the same y value along the x-axis. + - **X-Y Axis**: Show only the point being currently hovered over. + +###### X-Axis + +- **Generate X-Axis Tick Marks**: Select the method to generate x-axis tick marks: + - **Auto**: Select to automatically generate tick marks. + - **Custom**: To customize the number of x-axis tick marks, select this option, and then enter the following: + - **Total Tick Marks**: Enter the total number of timestamp ticks to display. + - **Start Tick Marks At**: Enter the time, in RFC3339 format, to start displaying ticks. Use the **Date Picker** field to automatically generate an RFC3339 formatted timestamp for this field. + - **Tick Mark Interval**: Enter the number of milliseconds in between each timestamp tick. + +###### Y-Axis + +- **Y Axis Label**: Enter the label for the y-axis. +- **Y-Value Unit Prefix**: Select the prefix to add to the y-value: + - **None**: Select to add no prefix. + - **SI**: (default) Select to add an International System of Units (SI) or metric prefix. + - **Binary**: Select to add a binary multiple prefix. +- **Y Axis Prefix**: Enter the prefix to add to the y-value. +- **Y Axis Suffix**: Enter the suffix to add to the y-value. +- **Generate Y-Axis Tick Marks**: Select the method to generate y-axis tick marks: + - **Auto**: Select to automatically generate tick marks. + - **Custom**: To customize the number of y-axis tick marks, select this option, and then enter the following: + - **Total Tick Marks**: Enter the total number of ticks to display. + - **Start Tick Marks At**: Enter the value to start ticks at. + - **Tick Mark Interval**: Enter the interval in between each tick. +- **Y Axis Domain**: Select the method to generate the y-axis value range: + - **Auto**: Select to automatically determine the value range based on values in the data set. + - **Custom**: To customize the y-axis domain, manually specify the minimum y-axis value, maximum y-axis value, or range by including both. + - **Min**: Enter the minimum y-axis value. + - **Max**: Enter the maximum y-axis value. + +###### Legend + +- **Hover Legend**: + - **Hide**: Hide the legend that appears upon hover. + - **Show**: Show the legend upon hover. + - **Orientation**: Select the orientation of the legend: + - **Horizontal**: Select to display the legend horizontally. + - **Vertical**: Select to display the legend vertically. + - **Opacity**: Adjust the hover legend opacity using the slider. + - **Colorize Rows**: Select to display hover legend rows in colors. +- **Static Legend**: + - **Hide**: Hide the static legend. + - **Show**: Always show the static legend. + - **Orientation**: Select the orientation of the legend: + - **Horizontal**: Select to display the legend horizontally. + - **Vertical**: Select to display the legend vertically. + - **Opacity**: Adjust the static legend opacity using the slider. + - **Colorize Rows**: Select to display static legend rows in colors. + - **Displayed Value**: Select **Latest Y Axis** or **Latest X Axis** to determine whether the y or x axis appears on the legend. + - **Height**: Adjust the height of the static legend using the slider. diff --git a/content/influxdb/v2.1/visualize-data/visualization-types/gauge.md b/content/influxdb/v2.1/visualize-data/visualization-types/gauge.md new file mode 100644 index 0000000000..0cb3a6716c --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/visualization-types/gauge.md @@ -0,0 +1,67 @@ +--- +title: Gauge visualization +list_title: Gauge +list_image: /img/influxdb/2-0-visualizations-gauge-example.png +description: > + The Gauge view displays the single value most recent value for a time series in a gauge view. +weight: 201 +menu: + influxdb_2_1: + name: Gauge + parent: Visualization types +--- + +The **Gauge** visualization displays the most recent value for a time series in a gauge. + +{{< img-hd src="/img/influxdb/2-0-visualizations-gauge-example-8.png" alt="Gauge example" />}} + +Select the **Gauge** option from the visualization dropdown in the upper left. + +## Gauge behavior +The gauge visualization displays a single numeric data point within a defined spectrum (_default is 0-100_). +It uses the latest point in the first table (or series) returned by the query. + +{{% note %}} +#### Queries should return one table +Flux does not guarantee the order in which tables are returned. +If a query returns multiple tables (or series), the table order can change between query executions +and result in the Gauge displaying inconsistent data. +For consistent results, the Gauge query should return a single table. +{{% /note %}} + +## Gauge Controls +To view **Gauge** controls, click **{{< icon "gear" >}} Customize** next to +the visualization dropdown. + +- **Prefix**: Prefix to add to the gauge. +- **Suffix**: Suffix to add to the gauge. +- **Decimal Places**: The number of decimal places to display for the gauge. + - **Auto** or **Custom**: Enable or disable auto-setting. + +###### Colorized Thresholds +- **Base Color**: Select a base or background color from the selection list. +- **Add a Threshold**: Change the color of the gauge based on the current value. + - **Value is**: Enter the value at which the gauge should appear in the selected color. + Choose a color from the dropdown menu next to the value. + +## Gauge examples +Gauge visualizations are useful for showing the current value of a metric and displaying +where it falls within a spectrum. + +### Steam pressure gauge +The following example queries sensor data that tracks the pressure of steam pipes +in a facility and displays it as a gauge. + +###### Query pressure data from a specific sensor +```js +from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => + r._measurement == "steam-sensors" and + r._field == "psi" + r.sensorID == "a211i" + ) +``` + +###### Visualization options for pressure gauge +{{< img-hd src="/img/influxdb/2-0-visualizations-gauge-pressure-8.png" alt="Pressure guage example" />}} diff --git a/content/influxdb/v2.1/visualize-data/visualization-types/graph-single-stat.md b/content/influxdb/v2.1/visualize-data/visualization-types/graph-single-stat.md new file mode 100644 index 0000000000..208420f93e --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/visualization-types/graph-single-stat.md @@ -0,0 +1,140 @@ +--- +title: Graph + Single Stat visualization +list_title: Graph + Single Stat +list_image: /img/influxdb/2-0-visualizations-line-graph-single-stat-example.png +description: > + The Graph + Single Stat view displays the specified time series in a line graph + and overlays the single most recent value as a large numeric value. +weight: 202 +menu: + influxdb_2_1: + name: Graph + Single Stat + parent: Visualization types +related: + - /influxdb/v2.1/visualize-data/visualization-types/graph + - /influxdb/v2.1/visualize-data/visualization-types/single-stat +--- + +The **Graph + Single Stat** view displays the specified time series in a line graph +and overlays the single most recent value as a large numeric value. + +{{< img-hd src="/img/influxdb/2-0-visualizations-line-graph-single-stat-example-8.png" alt="Line Graph + Single Stat example" />}} + +Select the **Graph + Single Stat** option from the visualization dropdown in the upper left. + +## Graph + Single Stat behavior +The Graph visualization color codes each table (or series) in the queried data set. +When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options). + +The Single Stat visualization displays a single numeric data point. +It uses the latest point in the first table (or series) returned by the query. + +{{% note %}} +#### Queries should return one table +Flux does not guarantee the order in which tables are returned. +If a query returns multiple tables (or series), the table order can change between query executions +and result in the Single Stat visualization displaying inconsistent data. +For consistent Single Stat results, the query should return a single table. +{{% /note %}} + +## Graph + Single Stat Controls +To view **Graph + Single Stat** controls, click **{{< icon "gear" >}} Customize** next to +the visualization dropdown. + +###### Data +- **X Column**: Select a column to display on the x-axis. +- **Y Column**: Select a column to display on the y-axis. +- **Time Format**: Select the time format. Options include: + {{< ui/timestamp-formats >}} + +###### Options +- **Line Colors**: Select a color scheme to use for your graph. +- **Shade Area Below Lines**: Shade in the area below the graph lines. +- **Hover Dimension**: Select the data to display in the tooltip when you hover over the graph: + - **auto** or **X Axis**: Show all points with the same x value along the y-axis. + - **Y Axis**: Show all points with the same y value along the x-axis. + - **X & Y Axis**: Show only the point currently being hovered over. + +###### X Axis +- **Generate X-Axis Tick Marks**: Select the method to generate x-axis tick marks: + - **Auto**: Select to automatically generate tick marks. + - **Custom**: To customize the number of x-axis tick marks, select this option, and then enter the following: + - **Total Tick Marks**: Enter the total number of ticks to display. + - **Start Tick Marks At**: Enter the value to start ticks at. + - **Tick Mark Interval**: Enter the interval in between each tick. + +###### Y Axis +- **Y Axis Label**: Label for the y-axis. +- **Y Value Unit Prefix**: + - **None**: No prefix. + - **SI**: International System of Units (SI) or metric prefix. + - **Binary**: Binary multiple prefix. +- **Y Axis Prefix**: Prefix to be added to y-value. +- **Y Axis Suffix**: Suffix to be added to y-value. +- **Generate Y-Axis Tick Marks**: Select the method to generate y-axis tick marks: + - **Auto**: Select to automatically generate tick marks. + - **Custom**: To customize the number of y-axis tick marks, select this option, and then enter the following: + - **Total Tick Marks**: Enter the total number of ticks to display. + - **Start Tick Marks At**: Enter the value to start ticks at. + - **Tick Mark Interval**: Enter the interval in between each tick. +- **Y Axis Domain**: The y-axis value range. + - **Auto**: Automatically determine the value range based on values in the data set. + - **Custom**: Manually specify the minimum y-axis value, maximum y-axis value, or range by including both. + - **Min**: Minimum y-axis value. + - **Max**: Maximum y-axis value. +- **Positioning**: + - **Overlaid**: Display graph lines overlaid on each other. + - **Stacked**: Display graph lines stacked on top of each other. + +###### Customize Single-Stat +- **Prefix**: Prefix to be added to the single stat. +- **Suffix**: Suffix to be added to the single stat. +- **Decimal Places**: The number of decimal places to display for the single stat. + - **Auto** or **Custom**: Enable or disable auto-setting. + +###### Colorized Thresholds +- **Base Color**: Select a base or background color from the selection list. +- **Add a Threshold**: Change the color of the single stat based on the current value. + - **Value is**: Enter the value at which the single stat should appear in the selected color. + Choose a color from the dropdown menu next to the value. +- **Colorization**: Choose **Text** for the single stat to change color based on the configured thresholds. + Choose **Background** for the background of the graph to change color based on the configured thresholds. + +###### Legend +- **Hover Legend**: + - **Hide**: Hide the legend that appears upon hover. + - **Show**: Show the legend upon hover. + - **Orientation**: Select the orientation of the legend: + - **Horizontal**: Select to display the legend horizontally. + - **Vertical**: Select to display the legend vertically. + - **Opacity**: Adjust the hover legend opacity using the slider. + - **Colorize Rows**: Select to display hover legend rows in colors. +- **Static Legend**: + - **Hide**: Hide the static legend. + - **Show**: Always show the static legend. + - **Orientation**: Select the orientation of the legend: + - **Horizontal**: Select to display the legend horizontally. + - **Vertical**: Select to display the legend vertically. + - **Opacity**: Adjust the static legend opacity using the slider. + - **Colorize Rows**: Select to display static legend rows in colors. + - **Displayed Value**: Select **Latest Y Axis** or **Latest X Axis** to determine whether the y or x axis appears on the legend. + - **Height**: Adjust the height of the static legend using the slider. + +## Graph + Single Stat examples +The primary use case for the Graph + Single Stat visualization is to show the current or latest +value as well as historical values. + +### Show current value and historical values +The following example shows the current percentage of memory used as well as memory usage over time: + +###### Query memory usage percentage +```js +from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) +``` +###### Memory allocations percentage visualization with static legend +{{< img-hd src="/img/influxdb/2-0-visualizations-graph-single-stat-static.png" alt="Graph + Single Stat Memory Usage Example" />}} diff --git a/content/influxdb/v2.1/visualize-data/visualization-types/graph.md b/content/influxdb/v2.1/visualize-data/visualization-types/graph.md new file mode 100644 index 0000000000..8fd3a1d4da --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/visualization-types/graph.md @@ -0,0 +1,113 @@ +--- +title: Graph visualization +list_title: Graph +list_image: /img/influxdb/2-0-visualizations-line-graph-example.png +description: > + The Graph view lets you select from multiple graph types such as line graphs and bar graphs *(Coming)*. +weight: 201 +menu: + influxdb_2_1: + name: Graph + parent: Visualization types +--- + +The Graph visualization provides several types of graphs, each configured through +the [Graph controls](#graph-controls). + +{{< img-hd src="/img/influxdb/2-0-visualizations-line-graph-example-8.png" alt="Line Graph example" />}} + +Select the **Graph** option from the visualization dropdown in the upper left. + +## Graph behavior +The Graph visualization color codes each table (or series) in the queried data set. +When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options). + +When using a line graph, all points within a single table are connected. When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options). + +## Graph controls +To view **Graph** controls, click **{{< icon "gear" >}} Customize** next to +the visualization dropdown. + +###### Data +- **X Column**: Select a column to display on the x-axis. +- **Y Column**: Select a column to display on the y-axis. +- **Time Format**: Select the time format. Options include: + {{< ui/timestamp-formats >}} + +###### Options +- **Interpolation**: Select from the following options: + - **Line**: Display a time series in a line graph + - **Smooth**: Display a time series in a line graph with smooth point interpolation. + - **Step**: Display a time series in a staircase graph. + + +- **Line Colors**: Select a color scheme to use for your graph. +- **Shade Area Below Lines**: Shade in the area below the graph lines. +- **Hover Dimension**: Select the data to display in the tooltip when you hover over the graph: + - **auto** or **X Axis**: Show all points with the same x value along the y-axis. + - **Y Axis**: Show all points with the same y value along the x-axis. + - **X & Y Axis**: Show only the point currently being hovered over. + +###### X Axis +- **Generate X-Axis Tick Marks**: Select the method to generate x-axis tick marks: + - **Auto**: Select to automatically generate tick marks. + - **Custom**: To customize the number of x-axis tick marks, select this option, and then enter the following: + - **Total Tick Marks**: Enter the total number of ticks to display. + - **Start Tick Marks At**: Enter the value to start ticks at. + - **Tick Mark Interval**: Enter the interval in between each tick. + +###### Y Axis +- **Y Axis Label**: Label for the y-axis. +- **Y Axis Prefix**: Prefix to be added to y-value. +- **Y Axis Suffix**: Suffix to be added to y-value. +- **Generate Y-Axis Tick Marks**: Select the method to generate y-axis tick marks: + - **Auto**: Select to automatically generate tick marks. + - **Custom**: To customize the number of y-axis tick marks, select this option, and then enter the following: + - **Total Tick Marks**: Enter the total number of ticks to display. + - **Start Tick Marks At**: Enter the value to start ticks at. + - **Tick Mark Interval**: Enter the interval in between each tick. +- **Y Axis Domain**: The y-axis value range. + - **Auto**: Automatically determine the value range based on values in the data set. + - **Custom**: Manually specify the minimum y-axis value, maximum y-axis value, or range by including both. + - **Min**: Minimum y-axis value. + - **Max**: Maximum y-axis value. +- **Positioning**: + - **Overlaid**: Display graph lines overlaid on each other. + - **Stacked**: Display graph lines stacked on top of each other. + +###### Legend +- **Hover Legend**: + - **Hide**: Hide the legend that appears upon hover. + - **Show**: Show the legend upon hover. + - **Orientation**: Select the orientation of the legend: + - **Horizontal**: Select to display the legend horizontally. + - **Vertical**: Select to display the legend vertically. + - **Opacity**: Adjust the hover legend opacity using the slider. + - **Colorize Rows**: Select to display hover legend rows in colors. +- **Static Legend**: + - **Hide**: Hide the static legend. + - **Show**: Always show the static legend. + - **Orientation**: Select the orientation of the legend: + - **Horizontal**: Select to display the legend horizontally. + - **Vertical**: Select to display the legend vertically. + - **Opacity**: Adjust the static legend opacity using the slider. + - **Colorize Rows**: Select to display static legend rows in colors. + - **Displayed Value**: Select **Latest Y Axis** or **Latest X Axis** to determine whether the y or x axis appears on the legend. + - **Height**: Adjust the height of the static legend using the slider. + +## Graph Examples + +##### Graph with linear interpolation and static legend +{{< img-hd src="/img/influxdb/2-0-visualizations-graph-linear-static.png" alt="Line Graph example" />}} + +##### Graph with smooth interpolation and hover legend +{{< img-hd src="/img/influxdb/2-0-visualizations-graph-smooth-hover.png" alt="Step-Plot Graph example" />}} + +##### Graph with step interpolation and no visible legend +{{< img-hd src="/img/influxdb/2-0-visualizations-line-graph-step-example-8.png" alt="Step-Plot Graph example" />}} + + + + diff --git a/content/influxdb/v2.1/visualize-data/visualization-types/heatmap.md b/content/influxdb/v2.1/visualize-data/visualization-types/heatmap.md new file mode 100644 index 0000000000..548807ec03 --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/visualization-types/heatmap.md @@ -0,0 +1,134 @@ +--- +title: Heatmap visualization +list_title: Heatmap +list_image: /img/influxdb/2-0-visualizations-heatmap-example.png +description: > + A Heatmap displays the distribution of data on an x and y axes where color + represents different concentrations of data points. +weight: 202 +menu: + influxdb_2_1: + name: Heatmap + parent: Visualization types +related: + - /influxdb/v2.1/visualize-data/visualization-types/scatter +--- + +A **Heatmap** displays the distribution of data on an x and y axes where color +represents different concentrations of data points. + +{{< img-hd src="/img/influxdb/2-0-visualizations-heatmap-example.png" alt="Heatmap example" />}} + +Select the **Heatmap** option from the visualization dropdown in the upper left. + +## Heatmap behavior +Heatmaps divide data points into "bins" – segments of the visualization with upper +and lower bounds for both [X and Y axes](#data). +The [Bin Size option](#options) determines the bounds for each bin. +The total number of points that fall within a bin determine the its value and color. +Warmer or brighter colors represent higher bin values or density of points within the bin. + +## Heatmap Controls +To view **Heatmap** controls, click **{{< icon "gear" >}} Customize** next to +the visualization dropdown. + +###### Data +- **X Column**: Select a column to display on the x-axis. +- **Y Column**: Select a column to display on the y-axis. +- **Time Format**: Select the time format. Options include: + {{< ui/timestamp-formats >}} + +###### Options +- **Color Scheme**: Select a color scheme to use for your heatmap. +- **Bin Size**: Specify the size of each bin. Default is 10. + +###### X Axis +- **X Axis Label**: Label for the x-axis. +- **Generate X-Axis Tick Marks**: Select the method to generate x-axis tick marks: + - **Auto**: Select to automatically generate tick marks. + - **Custom**: To customize the number of x-axis tick marks, select this option, and then enter the following: + - **Total Tick Marks**: Enter the total number of ticks to display. + - **Start Tick Marks At**: Enter the value to start ticks at. + - **Tick Mark Interval**: Enter the interval in between each tick. +- **X Axis Domain**: The x-axis value range. + - **Auto**: Automatically determine the value range based on values in the data set. + - **Custom**: Manually specify the minimum y-axis value, maximum y-axis value, or range by including both. + - **Min**: Minimum x-axis value. + - **Max**: Maximum x-axis value. + +###### Y Axis +- **Y Axis Label**: Label for the y-axis. +- **Y Tick Prefix**: Prefix to be added to y-value. +- **Y Tick Suffix**: Suffix to be added to y-value. +- **Generate Y-Axis Tick Marks**: Select the method to generate y-axis tick marks: + - **Auto**: Select to automatically generate tick marks. + - **Custom**: To customize the number of y-axis tick marks, select this option, and then enter the following: + - **Total Tick Marks**: Enter the total number of ticks to display. + - **Start Tick Marks At**: Enter the value to start ticks at. + - **Tick Mark Interval**: Enter the interval in between each tick. +- **Y Axis Domain**: The y-axis value range. + - **Auto**: Automatically determine the value range based on values in the data set. + - **Custom**: Manually specify the minimum y-axis value, maximum y-axis value, or range by including both. + - **Min**: Minimum y-axis value. + - **Max**: Maximum y-axis value. + +###### Legend +- **Legend Orientation**: Select the orientation of the legend that appears upon hover: + - **Horizontal**: Select to display the legend horizontally. + - **Vertical**: Select to display the legend vertically. +- **Opacity**: Adjust the legend opacity using the slider. +- **Colorize Rows**: Select to display legend rows in colors. + +## Heatmap examples + +### Cross-measurement correlation +The following example explores possible correlation between CPU and Memory usage. +It uses data collected with the Telegraf [Mem](/{{< latest "telegraf" >}}/plugins//#mem) +and [CPU](/{{< latest "telegraf" >}}/plugins//#cpu) input plugins. + +###### Join CPU and memory usage +The following query joins CPU and memory usage on `_time`. +Each row in the output table contains `_value_cpu` and `_value_mem` columns. + +```js +cpu = from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + +mem = from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + +join(tables: {cpu: cpu, mem: mem}, on: ["_time"], method: "inner") +``` + +###### Use a heatmap to visualize correlation +In the Heatmap visualization controls, `_value_cpu` is selected as the [X Column](#data) +and `_value_mem` is selected as the [Y Column](#data). +The domain for each axis is also customized to account for the scale difference +between column values. + +{{< img-hd src="/img/influxdb/2-0-visualizations-heatmap-correlation.png" alt="Heatmap correlation example" />}} + + +## Important notes + +### Differences between a heatmap and a scatter plot +Heatmaps and [Scatter plots](/influxdb/v2.1/visualize-data/visualization-types/scatter/) +both visualize the distribution of data points on X and Y axes. +However, in certain cases, heatmaps provide better visibility into point density. + +For example, the dashboard cells below visualize the same query results: + +{{< img-hd src="/img/influxdb/2-0-visualizations-heatmap-vs-scatter.png" alt="Heatmap vs Scatter plot" />}} + +The heatmap indicates isolated high point density, which isn't visible in the scatter plot. +In the scatter plot visualization, points that share the same X and Y coordinates +appear as a single point. diff --git a/content/influxdb/v2.1/visualize-data/visualization-types/histogram.md b/content/influxdb/v2.1/visualize-data/visualization-types/histogram.md new file mode 100644 index 0000000000..d93611207d --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/visualization-types/histogram.md @@ -0,0 +1,87 @@ +--- +title: Histogram visualization +list_title: Histogram +list_image: /img/influxdb/2-0-visualizations-histogram-example.png +description: > + A histogram is a way to view the distribution of data. + The y-axis is dedicated to count, and the x-axis is divided into bins. +weight: 202 +menu: + influxdb_2_1: + name: Histogram + parent: Visualization types +--- + +A histogram is a way to view the distribution of data. +The y-axis is dedicated to count, and the X-axis is divided into bins. + +{{< img-hd src="/img/influxdb/2-0-visualizations-histogram-example.png" alt="Histogram example" />}} + +Select the **Histogram** option from the visualization dropdown in the upper left. + +## Histogram behavior +The Histogram visualization is a bar graph that displays the number of data points +that fall within "bins" – segments of the X axis with upper and lower bounds. +Bin thresholds are determined by dividing the width of the X axis by the number +of bins set using the [Bins option](#options). +Data within bins can be further grouped or segmented by selecting columns in the +[Group By option](#options). + +{{% note %}} +The Histogram visualization automatically bins, segments, and counts data. +To work properly, query results **should not** be structured as histogram data. +{{% /note %}} + +## Histogram Controls +To view **Histogram** controls, click **{{< icon "gear" >}} Customize** next to +the visualization dropdown. + +###### Data +- **X Column**: The column to select data from. +- **Group By**: The column to group by. + +###### Options +- **Color Scheme**: Select a color scheme to use for your graph. +- **Positioning**: Select **Stacked** to stack groups in a bin on top of each other. + Select **Overlaid** to overlay groups in each bin. +- **Bins**: Enter a number of bins to divide data into or select Auto to automatically + calculate the number of bins. + - **Auto** or **Custom**: Enable or disable auto-setting. + +###### X Axis +- **X Axis Label**: Label for the x-axis. +- **X Axis Domain**: The x-axis value range. + - **Auto**: Automatically determine the value range based on values in the data set. + - **Custom**: Manually specify the value range of the x-axis. + - **Min**: Minimum x-axis value. + - **Max**: Maximum x-axis value. + +###### Legend +- **Legend Orientation**: Select the orientation of the legend that appears upon hover: + - **Horizontal**: Select to display the legend horizontally. + - **Vertical**: Select to display the legend vertically. +- **Opacity**: Adjust the legend opacity using the slider. +- **Colorize Rows**: Select to display legend rows in colors. + +## Histogram examples + +### View error counts by severity over time +The following example uses the Histogram visualization to show the number of errors +"binned" by time and segmented by severity. +_It utilizes data from the [Telegraf Syslog plugin](/{{< latest "telegraf" >}}/plugins//#syslog)._ + +##### Query for errors by severity code +```js +from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "syslog" and + r._field == "severity_code" + ) +``` + +##### Histogram settings +In the Histogram visualization options, select `_time` as the [X Column](#data) +and `severity` as the [Group By](#data) option: + +{{< img-hd src="/img/influxdb/2-0-visualizations-histogram-errors.png" alt="Errors histogram" />}} diff --git a/content/influxdb/v2.1/visualize-data/visualization-types/mosaic.md b/content/influxdb/v2.1/visualize-data/visualization-types/mosaic.md new file mode 100644 index 0000000000..37295d177e --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/visualization-types/mosaic.md @@ -0,0 +1,76 @@ +--- +title: Mosaic visualization +list_title: Mosaic +list_image: /img/influxdb/2-0-visualizations-mosaic-example.png +description: > + The Mosaic visualization displays state changes in your time series data. + This visualization type is useful when you want to show changes in string-based states over time. +weight: 202 +menu: + influxdb_2_1: + name: Mosaic + parent: Visualization types +--- + +The **Mosaic** visualization displays state changes in your time series data. +This visualization type is useful when you want to show changes in string-based states over time. + +{{< img-hd src="/img/influxdb/2-0-visualizations-mosaic-example.png" alt="Mosaic data visualization" />}} + +Select the **Mosaic** option from the visualization dropdown in the upper left. + +## Mosaic behavior +The mosaic visualization displays colored tiles based on string values in a specified column. +Each unique string value is represented by a different color. + +## Mosaic controls +To view **Mosaic** controls, click **{{< icon "gear" >}} Customize** next to the visualization dropdown. + +###### Data +- **Fill Column**: Select a column to fill in the mosaic tiles. +- **X Column**: Select a column to display on the x-axis. +- **Y Column**: Select one or more columns to display on the y-axis. +- **Time Format**: Select the time format. Options include: + {{< ui/timestamp-formats >}} + +###### Options +- **Color Scheme**: Select a color scheme to use for your graph. + +###### X Axis +- **X Axis Label**: Enter a label for the x-axis. +- **Generate X-Axis Tick Marks**: Select the method to generate x-axis tick marks: + - **Auto**: Select to automatically generate tick marks. + - **Custom**: To customize the number of x-axis tick marks, select this option, and then enter the following: + - **Total Tick Marks**: Enter the total number of timestamp ticks to display. + - **Start Tick Marks At**: Enter the time, in RFC3339 format, to start displaying ticks. Use the **Date Picker** field to automatically generate an RFC3339 formatted timestamp for this field. + - **Tick Mark Interval**: Enter the number of milliseconds in between each timestamp tick. + +###### Y Axis +- **Y Axis Label**: Enter a label for the y-axis. +- **Y Label Separator**: If there's more than one column on the y-axis, enter a delimiter to separate the label, such as a comma or space. If there's no separator specified, the labels are a continuous string of all y columns. +- **Generate Y-Axis Tick Marks**: Select the method to generate y-axis tick marks: + - **Auto**: Select to automatically generate tick marks. + - **Custom**: To customize the number of y-axis tick marks, select this option, and then enter the following: + - **Total Tick Marks**: Enter the total number of ticks to display. + - **Start Tick Marks At**: Enter the value to start ticks at. + - **Tick Mark Interval**: Enter the interval in between each tick. + +###### Legend +- **Legend Orientation**: Select the orientation of the legend that appears upon hover: + - **Horizontal**: Select to display the legend horizontally. + - **Vertical**: Select to display the legend vertically. +- **Opacity**: Adjust the legend opacity using the slider. +- **Colorize Rows**: Select to display legend rows in colors. + +## Example query +The following query uses the [NOAA water sample data](/influxdb/v2.1/reference/sample-data/#noaa-water-sample-data) +to display changes in water levels over time. +Use `level description` as the **Fill Column** in the [visualization controls](#data). + +```js +from(bucket: "noaa") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => r._measurement == "h2o_feet") + |> filter(fn: (r) => r._field == "level description") + |> aggregateWindow(every: v.windowPeriod, fn: last, createEmpty: false) +``` diff --git a/content/influxdb/v2.1/visualize-data/visualization-types/scatter.md b/content/influxdb/v2.1/visualize-data/visualization-types/scatter.md new file mode 100644 index 0000000000..231b4ced28 --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/visualization-types/scatter.md @@ -0,0 +1,136 @@ +--- +title: Scatter visualization +list_title: Scatter +list_image: /img/influxdb/2-0-visualizations-scatter-example.png +description: > + The Scatter view uses a scatter plot to display time series data. +weight: 202 +menu: + influxdb_2_1: + name: Scatter + parent: Visualization types +related: + - /influxdb/v2.1/visualize-data/visualization-types/heatmap +--- + +The **Scatter** view uses a scatter plot to display time series data. + +{{< img-hd src="/img/influxdb/2-0-visualizations-scatter-example.png" alt="Scatter plot example" />}} + +Select the **Scatter** option from the visualization dropdown in the upper left. + +## Scatter behavior +The scatter visualization maps each data point to X and Y coordinates. +X and Y axes are specified with the [X Column](#data) and [Y Column](#data) visualization options. +Each unique series is differentiated using fill colors and symbols. +Use the [Symbol Column](#data) and [Fill Column](#data) options to select columns +used to differentiate points in the visualization. + +## Scatter controls +To view **Scatter** controls, click **{{< icon "gear" >}} Customize** next to +the visualization dropdown. + +###### Data +- **Symbol Column**: Define a column containing values that should be differentiated with symbols. +- **Fill Column**: Define a column containing values that should be differentiated with fill color. +- **X Column**: Select a column to display on the x-axis. +- **Y Column**: Select a column to display on the y-axis. +- **Time Format**: Select the time format. Options include: + {{< ui/timestamp-formats >}} + +###### Options +- **Color Scheme**: Select a color scheme to use for your scatter plot. + +###### X Axis +- **X Axis Label**: Label for the x-axis. +- **Generate X-Axis Tick Marks**: Select the method to generate x-axis tick marks: + - **Auto**: Select to automatically generate tick marks. + - **Custom**: To customize the number of x-axis tick marks, select this option, and then enter the following: + - **Total Tick Marks**: Enter the total number of ticks to display. + - **Start Tick Marks At**: Enter the value to start ticks at. + - **Tick Mark Interval**: Enter the interval in between each tick. +- **X Axis Domain**: The x-axis value range. + - **Auto**: Automatically determine the value range based on values in the data set. + - **Custom**: Manually specify the minimum x-axis value, maximum x-axis value, or range by including both. + - **Min**: Minimum x-axis value. + - **Max**: Maximum x-axis value. + +###### Y Axis +- **Y Axis Label**: Label for the y-axis. +- **Y Tick Prefix**: Prefix to be added to y-value. +- **Y Tick Suffix**: Suffix to be added to y-value. +- **Generate Y-Axis Tick Marks**: Select the method to generate y-axis tick marks: + - **Auto**: Select to automatically generate tick marks. + - **Custom**: To customize the number of y-axis tick marks, select this option, and then enter the following: + - **Total Tick Marks**: Enter the total number of ticks to display. + - **Start Tick Marks At**: Enter the value to start ticks at. + - **Tick Mark Interval**: Enter the interval in between each tick. +- **Y Axis Domain**: The y-axis value range. + - **Auto**: Automatically determine the value range based on values in the data set. + - **Custom**: Manually specify the minimum y-axis value, maximum y-axis value, or range by including both. + - **Min**: Minimum y-axis value. + - **Max**: Maximum y-axis value. + +###### Legend +- **Legend Orientation**: Select the orientation of the legend that appears upon hover: + - **Horizontal**: Select to display the legend horizontally. + - **Vertical**: Select to display the legend vertically. +- **Opacity**: Adjust the legend opacity using the slider. +- **Colorize Rows**: Select to display legend rows in colors. + +## Scatter examples + +### Cross-measurement correlation +The following example explores possible correlation between CPU and Memory usage. +It uses data collected with the Telegraf [Mem](/{{< latest "telegraf" >}}/plugins//#mem) +and [CPU](/{{< latest "telegraf" >}}/plugins//#cpu) input plugins. + +###### Query CPU and memory usage +The following query creates a union of CPU and memory usage. +It scales the CPU usage metric to better align with baseline memory usage. + +```js +cpu = from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + // Scale CPU usage + |> map(fn: (r) => ({ + r with + _value: r._value + 60.0, + _time: r._time + }) + ) + +mem = from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + +union(tables: [cpu, mem]) +``` + +###### Use a scatter plot to visualize correlation +In the Scatter visualization controls, points are differentiated based on their group keys. + +{{< img-hd src="/img/influxdb/2-0-visualizations-scatter-correlation.png" alt="Heatmap correlation example" />}} + +## Important notes + +### Differences between a scatter plot and a heatmap +Scatter plots and [Heatmaps](/influxdb/v2.1/visualize-data/visualization-types/heatmap/) +both visualize the distribution of data points on X and Y axes. +However, in certain cases, scatterplots can "hide" points if they share the same X and Y coordinates. + +For example, the dashboard cells below visualize the same query results: + +{{< img-hd src="/img/influxdb/2-0-visualizations-heatmap-vs-scatter.png" alt="Heatmap vs Scatter plot" />}} + +The heatmap indicates isolated high point density, which isn't visible in the scatter plot. +In the scatter plot visualization, points that share the same X and Y coordinates +appear as a single point. diff --git a/content/influxdb/v2.1/visualize-data/visualization-types/single-stat.md b/content/influxdb/v2.1/visualize-data/visualization-types/single-stat.md new file mode 100644 index 0000000000..7f90578e39 --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/visualization-types/single-stat.md @@ -0,0 +1,65 @@ +--- +title: Single Stat visualization +list_title: Single stat +list_image: /img/influxdb/2-0-visualizations-single-stat-example.png +description: > + The Single Stat view displays the most recent value of the specified time series as a numerical value. +weight: 202 +menu: + influxdb_2_1: + name: Single Stat + parent: Visualization types +--- + +The **Single Stat** view displays the most recent value of the specified time series as a numerical value. + +{{< img-hd src="/img/influxdb/2-0-visualizations-single-stat-example-8.png" alt="Single stat example" />}} + +Select the **Single Stat** option from the visualization dropdown in the upper left. + +## Single Stat behavior +The Single Stat visualization displays a single numeric data point. +It uses the latest point in the first table (or series) returned by the query. + +{{% note %}} +#### Queries should return one table +Flux does not guarantee the order in which tables are returned. +If a query returns multiple tables (or series), the table order can change between query executions +and result in the Single Stat visualization displaying inconsistent data. +For consistent results, the Single Stat query should return a single table. +{{% /note %}} + +## Single Stat Controls +To view **Single Stat** controls, click **{{< icon "gear" >}} Customize** next to +the visualization dropdown. + +- **Prefix**: Prefix to be added to the single stat. +- **Suffix**: Suffix to be added to the single stat. +- **Decimal Places**: The number of decimal places to display for the single stat. + - **Auto** or **Custom**: Enable or disable auto-setting. + +###### Colorized Thresholds +- **Base Color**: Select a base or background color from the selection list. +- **Add a Threshold**: Change the color of the single stat based on the current value. + - **Value is**: Enter the value at which the single stat should appear in the selected color. + Choose a color from the dropdown menu next to the value. +- **Colorization**: Choose **Text** for the single stat to change color based on the configured thresholds. + Choose **Background** for the background of the graph to change color based on the configured thresholds. + +## Single Stat examples + +### Show human-readable current value +The following example shows the current memory usage displayed has a human-readable percentage: + +###### Query memory usage percentage +```js +from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) +``` + +###### Memory usage as a single stat +{{< img-hd src="/img/influxdb/2-0-visualizations-single-stat-example-8.png" alt="Graph + Single Stat Memory Usage Example" />}} diff --git a/content/influxdb/v2.1/visualize-data/visualization-types/table.md b/content/influxdb/v2.1/visualize-data/visualization-types/table.md new file mode 100644 index 0000000000..0c18181d39 --- /dev/null +++ b/content/influxdb/v2.1/visualize-data/visualization-types/table.md @@ -0,0 +1,78 @@ +--- +title: Table visualization +list_title: Table +list_image: /img/influxdb/2-0-visualizations-table-example.png +description: > + The Table option displays the results of queries in a tabular view, which is + sometimes easier to analyze than graph views of data. +weight: 202 +menu: + influxdb_2_1: + name: Table + parent: Visualization types +--- + +The **Table** option displays the results of queries in a tabular view, which is +sometimes easier to analyze than graph views of data. + +{{< img-hd src="/img/influxdb/2-0-visualizations-table-example.png" alt="Table example" />}} + +Select the **Table** option from the visualization dropdown in the upper left. + +## Table behavior +The table visualization renders queried data in structured, easy-to-read tables. +Columns and rows match those in the query output. +If query results contain multiple tables, only one table is shown at a time. +Select other output tables in the far left column of the table visualization. +Tables are identified by their [group key](/{{< latest "flux" >}}/get-started/data-model/#group-key). + +## Table Controls +To view **Table** controls, click **{{< icon "gear" >}} Customize** next to +the visualization dropdown. + +###### Formatting +- **Default Sort Field**: Select the default sort field. Default is **time**. +- **Time Format**: Select the time format. Options include: + {{< ui/timestamp-formats >}} + +- **Decimal Places**: Enter the number of decimal places. Default (empty field) is **unlimited**. + - **Auto** or **Custom**: Enable or disable auto-setting. + +###### Colorized Thresholds +- **Base Color**: Select a base or background color from the selection list. +- **Add a Threshold**: Change the color of the table based on the current value. + - **Value is**: Enter the value at which the table should appear in the selected color. + Choose a color from the dropdown menu next to the value. + +###### Column Settings +- **First Column**: Toggle to **Fixed** to lock the first column so that the listings are always visible. + Threshold settings do not apply in the first column when locked. +- **Table Columns**: + - Enter a new name to rename any of the columns. + - Click the eye icon next to a column to hide it. + - [additional]: Enter name for each additional column. + - Change the order of the columns by dragging to the desired position. + +## Table examples +Tables are helpful when displaying many human-readable metrics in a dashboard +such as cluster statistics or log messages. + +### Human-readable cluster metrics +The following example queries the latest reported memory usage from a cluster of servers. + +###### Query the latest memory usage from each host +```js +from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> group(columns: ["host"]) + |> last() + |> group() + |> keep(columns: ["_value", "host"]) +``` + +###### Cluster metrics in a table +{{< img-hd src="/img/influxdb/2-0-visualizations-table-human-readable.png" alt="Human readable metrics in a table" />}} diff --git a/content/influxdb/v2.1/write-data/_index.md b/content/influxdb/v2.1/write-data/_index.md new file mode 100644 index 0000000000..78ebde0425 --- /dev/null +++ b/content/influxdb/v2.1/write-data/_index.md @@ -0,0 +1,30 @@ +--- +title: Write data to InfluxDB +list_title: Write data +description: > + Collect and write time series data to InfluxDB Cloud and InfluxDB OSS. +weight: 4 +aliases: + - /influxdb/v2.1/write-data/quick-start/ + - /influxdb/v2.1/write-data/sample-data/demo-data/ +menu: + influxdb_2_1: + name: Write data +influxdb/v2.1/tags: [write, line protocol] +related: + - /influxdb/v2.1/write-data/no-code/use-telegraf/ + - /influxdb/v2.1/api/#tag/Write, InfluxDB API /write endpoint + - /influxdb/v2.1/reference/syntax/line-protocol + - /influxdb/v2.1/reference/syntax/annotated-csv + - /influxdb/v2.1/reference/cli/influx/write +--- + +1. Learn the [best practices](/influxdb/v2.1/write-data/best-practices/) for writing data. +2. Discover how to write data [without coding](/influxdb/v2.1/write-data/no-code/), by [loading data source in the UI](/influxdb/v2.1/write-data/load-data/), or using [developer tools](/influxdb/v2.1/write-data/developer-tools/). +3. Do any of the following: + - [Troubleshoot the most common issues writing data](/influxdb/v2.1/write-data/troubleshoot/) + - [Delete data you no longer need](/influxdb/v2.1/write-data/delete-data/) + - [Query and explore data](/influxdb/v2.1/query-data/) + - [Process data](/influxdb/v2.1/process-data/) + - [Visualize data](/influxdb/v2.1/visualize-data/) + - [Monitor and alert](/influxdb/v2.1/monitor-alert/) \ No newline at end of file diff --git a/content/influxdb/v2.1/write-data/best-practices/_index.md b/content/influxdb/v2.1/write-data/best-practices/_index.md new file mode 100644 index 0000000000..ba515e63bf --- /dev/null +++ b/content/influxdb/v2.1/write-data/best-practices/_index.md @@ -0,0 +1,17 @@ +--- +title: Best practices for writing data +seotitle: Best practices for writing data to InfluxDB +description: > + Learn about the recommendations and best practices for writing data to InfluxDB. +weight: 105 +menu: + influxdb_2_1: + name: Best practices + identifier: write-best-practices + parent: Write data +--- + +The following articles walk through recommendations and best practices for writing +data to InfluxDB. + +{{< children >}} diff --git a/content/influxdb/v2.1/write-data/best-practices/duplicate-points.md b/content/influxdb/v2.1/write-data/best-practices/duplicate-points.md new file mode 100644 index 0000000000..8bd550645f --- /dev/null +++ b/content/influxdb/v2.1/write-data/best-practices/duplicate-points.md @@ -0,0 +1,131 @@ +--- +title: Handle duplicate data points +seotitle: Handle duplicate data points when writing to InfluxDB +description: > + InfluxDB identifies unique data points by their measurement, tag set, and timestamp. + This article discusses methods for preserving data from two points with a common + measurement, tag set, and timestamp but a different field set. +weight: 204 +menu: + influxdb_2_1: + name: Handle duplicate points + parent: write-best-practices +influxdb/v2.1/tags: [best practices, write] +--- + +InfluxDB identifies unique data points by their measurement, tag set, and timestamp +(each a part of [Line protocol](/influxdb/v2.1/reference/syntax/line-protocol) used to write data to InfluxDB). + +```txt +web,host=host2,region=us_west firstByte=15.0 1559260800000000000 +--- ------------------------- ------------------- + | | | +Measurement Tag set Timestamp +``` + +## Duplicate data points +For points that have the same measurement name, tag set, and timestamp, +InfluxDB creates a union of the old and new field sets. +For any matching field keys, InfluxDB uses the field value of the new point. +For example: + +```sh +# Existing data point +web,host=host2,region=us_west firstByte=24.0,dnsLookup=7.0 1559260800000000000 + +# New data point +web,host=host2,region=us_west firstByte=15.0 1559260800000000000 +``` + +After you submit the new data point, InfluxDB overwrites `firstByte` with the new +field value and leaves the field `dnsLookup` alone: + +```sh +# Resulting data point +web,host=host2,region=us_west firstByte=15.0,dnsLookup=7.0 1559260800000000000 +``` + +```sh +from(bucket: "example-bucket") + |> range(start: 2019-05-31T00:00:00Z, stop: 2019-05-31T12:00:00Z) + |> filter(fn: (r) => r._measurement == "web") + +Table: keys: [_measurement, host, region] + _time _measurement host region dnsLookup firstByte +-------------------- ------------ ----- ------- --------- --------- +2019-05-31T00:00:00Z web host2 us_west 7 15 +``` + +## Preserve duplicate points +To preserve both old and new field values in duplicate points, use one of the following strategies: + +- [Add an arbitrary tag](#add-an-arbitrary-tag) +- [Increment the timestamp](#increment-the-timestamp) + +### Add an arbitrary tag +Add an arbitrary tag with unique values so InfluxDB reads the duplicate points as unique. + +For example, add a `uniq` tag to each data point: + +```sh +# Existing point +web,host=host2,region=us_west,uniq=1 firstByte=24.0,dnsLookup=7.0 1559260800000000000 + +# New point +web,host=host2,region=us_west,uniq=2 firstByte=15.0 1559260800000000000 +``` + +{{% note %}} +It is not necessary to retroactively add the unique tag to the existing data point. +Tag sets are evaluated as a whole. +The arbitrary `uniq` tag on the new point allows InfluxDB to recognize it as a unique point. +However, this causes the schema of the two points to differ and may lead to challenges when querying the data. +{{% /note %}} + +After writing the new point to InfluxDB: + +```sh +from(bucket: "example-bucket") + |> range(start: 2019-05-31T00:00:00Z, stop: 2019-05-31T12:00:00Z) + |> filter(fn: (r) => r._measurement == "web") + +Table: keys: [_measurement, host, region, uniq] + _time _measurement host region uniq firstByte dnsLookup +-------------------- ------------ ----- ------- ---- --------- --------- +2019-05-31T00:00:00Z web host2 us_west 1 24 7 + +Table: keys: [_measurement, host, region, uniq] + _time _measurement host region uniq firstByte +-------------------- ------------ ----- ------- ---- --------- +2019-05-31T00:00:00Z web host2 us_west 2 15 +``` + +### Increment the timestamp +Increment the timestamp by a nanosecond to enforce the uniqueness of each point. + +```sh +# Old data point +web,host=host2,region=us_west firstByte=24.0,dnsLookup=7.0 1559260800000000000 + +# New data point +web,host=host2,region=us_west firstByte=15.0 1559260800000000001 +``` + +After writing the new point to InfluxDB: + +```sh +from(bucket: "example-bucket") + |> range(start: 2019-05-31T00:00:00Z, stop: 2019-05-31T12:00:00Z) + |> filter(fn: (r) => r._measurement == "web") + +Table: keys: [_measurement, host, region] + _time _measurement host region firstByte dnsLookup +------------------------------ ------------ ----- ------- --------- --------- +2019-05-31T00:00:00.000000000Z web host2 us_west 24 7 +2019-05-31T00:00:00.000000001Z web host2 us_west 15 +``` + +{{% note %}} +The output of examples queries in this article has been modified to clearly show +the different approaches and results for handling duplicate data. +{{% /note %}} diff --git a/content/influxdb/v2.1/write-data/best-practices/optimize-writes.md b/content/influxdb/v2.1/write-data/best-practices/optimize-writes.md new file mode 100644 index 0000000000..152cdb6278 --- /dev/null +++ b/content/influxdb/v2.1/write-data/best-practices/optimize-writes.md @@ -0,0 +1,132 @@ +--- +title: Optimize writes to InfluxDB +description: > + Simple tips to optimize performance and system overhead when writing data to InfluxDB. +weight: 203 +menu: + influxdb_2_1: + parent: write-best-practices +influxdb/v2.1/tags: [best practices, write] +--- + +Use these tips to optimize performance and system overhead when writing data to InfluxDB. + +- [Batch writes](#batch-writes) +- [Sort tags by key](#sort-tags-by-key) +- [Use the coarsest time precision possible](#use-the-coarsest-time-precision-possible) +- [Use gzip compression](#use-gzip-compression) +- [Synchronize hosts with NTP](#synchronize-hosts-with-ntp) +- [Write multiple data points in one request](#write-multiple-data-points-in-one-request) + +{{% note %}} +The following tools write to InfluxDB and employ _most_ write optimizations by default: + +- [Telegraf](/influxdb/v2.1/write-data/no-code/use-telegraf/) +- [InfluxDB client libraries](/influxdb/v2.1/api-guide/client-libraries/) +- [InfluxDB scrapers](/influxdb/v2.1/write-data/no-code/scrape-data/) +{{% /note %}} + +## Batch writes + +Write data in batches to minimize network overhead when writing data to InfluxDB. + +{{% note %}} +The optimal batch size is 5000 lines of line protocol. +{{% /note %}} + +## Sort tags by key + +Before writing data points to InfluxDB, sort tags by key in lexicographic order. +_Verify sort results match results from the [Go `bytes.Compare` function](http://golang.org/pkg/bytes/#Compare)._ + +```sh +# Line protocol example with unsorted tags +measurement,tagC=therefore,tagE=am,tagA=i,tagD=i,tagB=think fieldKey=fieldValue 1562020262 + +# Optimized line protocol example with tags sorted by key +measurement,tagA=i,tagB=think,tagC=therefore,tagD=i,tagE=am fieldKey=fieldValue 1562020262 +``` + +## Use the coarsest time precision possible + +By default, InfluxDB writes data in nanosecond precision. +However if your data isn't collected in nanoseconds, there is no need to write at that precision. +For better performance, use the coarsest precision possible for timestamps. + +_Specify timestamp precision when [writing to InfluxDB](/influxdb/v2.1/write-data/#timestamp-precision)._ + +## Use gzip compression + +Use gzip compression to speed up writes to InfluxDB and reduce network bandwidth. +Benchmarks have shown up to a 5x speed improvement when data is compressed. + +{{< tabs-wrapper >}} +{{% tabs %}} +[Telegraf](#) +[Client libraries](#) +[InfluxDB API](#) +{{% /tabs %}} +{{% tab-content %}} + +### Enable gzip compression in Telegraf + +In the `influxdb_v2` output plugin configuration in your `telegraf.conf`, set the +`content_encoding` option to `gzip`: + +```toml +[[outputs.influxdb_v2]] + urls = ["http://localhost:8086"] + # ... + content_encoding = "gzip" +``` +{{% /tab-content %}} +{{% tab-content %}} + +### Enable gzip compression in InfluxDB client libraries + +Each [InfluxDB client library](/influxdb/v2.1/api-guide/client-libraries/) provides +options for compressing write requests or enforces compression by default. +The method for enabling compression is different for each library. +For specific instructions, see the [InfluxDB client libraries documentation](/influxdb/v2.1/api-guide/client-libraries/). +{{% /tab-content %}} +{{% tab-content %}} + +### Use gzip compression with the InfluxDB API + +When using the InfluxDB API `/write` endpoint to write data, compress the data with `gzip` and set the `Content-Encoding` +header to `gzip`. + +```sh +{{% get-shared-text "api/v2.0/write/write-compress.sh" %}} +``` +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +## Synchronize hosts with NTP + +Use the Network Time Protocol (NTP) to synchronize time between hosts. +If a timestamp isn't included in line protocol, InfluxDB uses its host's local +time (in UTC) to assign timestamps to each point. +If a host's clocks isn't synchronized with NTP, timestamps may be inaccurate. + +## Write multiple data points in one request + +To write multiple lines in one request, each line of line protocol must be delimited by a new line (`\n`). + +## Rate limiting + +Use the [`influx write`](/influxdb/v2.1/reference/cli/influx/write/) `--rate-limit` flag to control the rate of writes. +Use one of the following string formats to specify the rate limit: + +- `COUNT(B|kB|MB)`, or +- `COUNT(B|kB|MB)/TIME(s|sec|m|min)` + +where `COUNT` is a decimal number and `TIME` is a positive whole number. +Spaces in the value are ignored. +For example: "5MB / 5min" can be also expressed as `17476.266666667Bs`, `1MB/1min`, `1MB/min`, `1MBmin` or `1MBm`. +If the rate limit format is invalid, `influx write` prints out the format and an exact regular expression. +The `--rate-limit` flag can be also used with [`influx write dryrun`](/influxdb/v2.1/reference/cli/influx/write/dryrun/). + +{{% cloud %}} +By default, the free tier rate limit in {{< cloud-name "short" >}} is `1MB/min`. +{{% /cloud %}} diff --git a/content/influxdb/v2.1/write-data/best-practices/resolve-high-cardinality.md b/content/influxdb/v2.1/write-data/best-practices/resolve-high-cardinality.md new file mode 100644 index 0000000000..d68e6cd94d --- /dev/null +++ b/content/influxdb/v2.1/write-data/best-practices/resolve-high-cardinality.md @@ -0,0 +1,117 @@ +--- +title: Resolve high series cardinality +description: > + Reduce high series cardinality in InfluxDB. If reads and writes to InfluxDB have started to slow down, you may have high cardinality. Find the source of high cardinality and adjust your schema to resolve high cardinality issues. +menu: + influxdb_2_1: + name: Resolve high cardinality + weight: 202 + parent: write-best-practices +--- + +If reads and writes to InfluxDB have started to slow down, high [series cardinality](/influxdb/v2.1/reference/glossary/#series-cardinality) (too many series) may be causing memory issues. + +To resolve high series cardinality, complete the following steps (for multiple buckets if applicable): + +1. [Review tags](#review-tags). +2. [Adjust your schema](#adjust-your-schema). + +## Review tags + +Review your tags to ensure each tag **does not contain** unique values for most entries: + +- Scan your tags for [common tag issues](#common-tag-issues). +- Use the example Flux query below to [count unique tag values](#count-unique-tag-values). + +### Common tag issues + +Look for the following common issues, which often cause many unique tag values: + +- **Writing log messages to tags**. If a log message includes a unique timestamp, pointer value, or unique string, many unique tag values are created. +- **Writing timestamps to tags**. Typically done by accident in client code. +- **Unique tag values that grow over time** For example, a user ID tag may work at a small startup, but may begin to cause issues when the company grows to hundreds of thousands of users. + +### Count unique tag values + +The following example Flux query shows you which tags are contributing the most to cardinality. Look for tags with values orders of magnitude higher than others. + +```js +// Count unique values for each tag in a bucket +import "influxdata/influxdb/schema" + +cardinalityByTag = (bucket) => + schema.tagKeys(bucket: bucket) + |> map(fn: (r) => ({ + tag: r._value, + _value: + if contains(set: ["_stop","_start"], value:r._value) then 0 + else (schema.tagValues(bucket: bucket, tag: r._value) + |> count() + |> findRecord(fn: (key) => true, idx: 0))._value + })) + |> group(columns:["tag"]) + |> sum() + +cardinalityByTag(bucket: "example-bucket") +``` + +{{% note %}} + If you're experiencing runaway cardinality, the query above may timeout. If you experience a timeout, run the queries below—one at a time. +{{% /note %}} + +1. Generate a list of tags: + + ```js + // Generate a list of tags + import "influxdata/influxdb/schema" + + schema.tagKeys(bucket: "example-bucket") + ``` + +2. Count unique tag values for each tag: + + ```js + // Run the following for each tag to count the number of unique tag values + import "influxdata/influxdb/schema" + + tag = "example-tag-key" + + schema.tagValues(bucket: "my-bucket", tag: tag) + |> count() + ``` + +These queries should help to identify the sources of high cardinality in each of your buckets. To determine which specific tags are growing, check the cardinality again after 24 hours to see if one or more tags have grown significantly. + +## Adjust your schema + +Usually, resolving high cardinality is as simple as changing a tag with many unique values to a field. Review the following potential solutions for resolving high cardinality: + +- Delete data to reduce high cardinality +- Design schema for read performance + +### Delete data to reduce high cardinality + +Consider whether you need the data causing high cardinality. In some cases, you may decide you no longer need this data, in which case you may choose to [delete the whole bucket](/influxdb/v2.1/organizations/buckets/delete-bucket/) or [delete a range of data](/influxdb/v2.1/write-data/delete-data/). + +### Design schema for read performance + +Tags are valuable for indexing, so during a query, the query engine doesn't need to scan every single record in a bucket. However, too many indexes may create performance problems. The trick is to create a middle ground between scanning and indexing. + +For example, if you query for specific user IDs with thousands of users, a simple query like this, where `userId` is a field, requires InfluxDB to scan every row for the `userId`: + +```js +from(bucket: "example-bucket") + |> range(start: -7d) + |> filter(fn: (r) => r._field == "userId" and r._value == "abcde") +``` + +If you include a tag in your schema that can be reasonably indexed, such as a `company` tag, you can reduce the number of rows scanned and retrieve data more quickly: + +```js +from(bucket: "example-bucket") + |> range(start: -7d) + |> filter(fn: (r) => r.company == "Acme") + |> filter(fn: (r) => r._field == "userId" and r._value == "abcde") +``` + +Consider tags that can be reasonably indexed to make your queries more performant. For more guidelines to consider, see [InfluxDB schema design](/influxdb/v2.1/write-data/best-practices/schema-design/). diff --git a/content/influxdb/v2.1/write-data/best-practices/schema-design.md b/content/influxdb/v2.1/write-data/best-practices/schema-design.md new file mode 100644 index 0000000000..6857ddab80 --- /dev/null +++ b/content/influxdb/v2.1/write-data/best-practices/schema-design.md @@ -0,0 +1,228 @@ +--- +title: InfluxDB schema design +description: > + Improve InfluxDB schema design and data layout to reduce high cardinality and make your data more performant. +menu: + influxdb_2_1: + name: Schema design + weight: 201 + parent: write-best-practices +--- + +Each InfluxDB use case is unique and your [schema](/influxdb/v2.1/reference/glossary/#schema) design reflects the uniqueness. We recommend the following design guidelines for most use cases: + +- [Where to store data (tag or field)](#where-to-store-data-tags-or-fields) +- [Avoid too many series](#avoid-too-many-series) +- [Use recommended naming conventions](#use-recommended-naming-conventions) + + +{{% note %}} +Follow these guidelines to minimize high series cardinality and make your data more performant. +{{% /note %}} + +## Where to store data (tag or field) + +[Tags](/influxdb/v2.1/reference/glossary/#tag) are indexed and [fields](/influxdb/v2.1/reference/glossary/#field) are not. +This means that querying by tags is more performant than querying by fields. + +In general, your queries should guide what gets stored as a tag and what gets stored as a field: + +- Store commonly-queried meta data in tags. +- Store data in fields if each data point contains a different value. +- Store numeric values as fields ([tag values](/influxdb/v2.1/reference/glossary/#tag-value) only support string values). + +## Avoid too many series + +[Tags](/influxdb/v2.1/reference/glossary/#tag) containing highly variable information like unique IDs, hashes, and random strings lead to a large number of [series](/influxdb/v2.1/reference/glossary/#series), also known as high [series cardinality](/influxdb/v2.1/reference/glossary/#series-cardinality). + +High series cardinality is a primary driver of high memory usage for many database workloads. +InfluxDB uses measurements and tags to create indexes and speed up reads. However, when too many indexes created, both writes and reads may start to slow down. Therefore, if a system has memory constraints, consider storing high-cardinality data as a field rather than a tag. + +{{% note %}} +If reads and writes to InfluxDB start to slow down, you may have high series cardinality (too many series). See how to [resolve high cardinality](/influxdb/v2.1/write-data/best-practices/resolve-high-cardinality/). +{{% /note %}} + +## Use recommended naming conventions + +Use the following conventions when naming your tag and field keys: + +- [Avoid keywords in tag and field names](#avoid-keywords-as-tag-or-field-names) +- [Avoid the same tag and field name](#avoid-the-same-name-for-a-tag-and-a-field) +- [Avoid encoding data in measurement names](#avoid-encoding-data-in-measurement-names) +- [Avoid more than one piece of information in one tag](#avoid-putting-more-than-one-piece-of-information-in-one-tag) + +### Avoid keywords as tag or field names + +Not required, but simplifies writing queries because you won't have to wrap tag or field names in double quotes. +See [Flux keywords](/{{< latest "flux" >}}/spec/lexical-elements/#keywords) to avoid. + +Also, if a tag or field name contains non-alphanumeric characters, you must use [bracket notation](/{{< latest "flux" >}}/data-types/composite/record/#bracket-notation) in Flux. + +### Avoid the same name for a tag and a field + +Avoid using the same name for a tag and field key, which may result in unexpected behavior when querying data. + +### Avoid encoding data in measurement names + +InfluxDB queries merge data that falls within the same [measurement](/influxdb/v2.1/reference/glossary/#measurement), so it's better to differentiate data with [tags](/influxdb/v2.1/reference/glossary/#tag) than with detailed measurement names. If you encode data in a measurement name, you must use a regular expression to query the data, making some queries more complicated. + +#### Example line protocol schemas + +Consider the following schema represented by line protocol. + +``` +Schema 1 - Data encoded in the measurement name +------------- +blueberries.plot-1.north temp=50.1 1472515200000000000 +blueberries.plot-2.midwest temp=49.8 1472515200000000000 +``` + +The long measurement names (`blueberries.plot-1.north`) with no tags are similar to Graphite metrics. +Encoding the `plot` and `region` in the measurement name makes the data more difficult to query. + +For example, calculating the average temperature of both plots 1 and 2 is not possible with schema 1. +Compare this to schema 2: + +``` +Schema 2 - Data encoded in tags +------------- +weather_sensor,crop=blueberries,plot=1,region=north temp=50.1 1472515200000000000 +weather_sensor,crop=blueberries,plot=2,region=midwest temp=49.8 1472515200000000000 +``` + +#### Flux example to query schemas + +Use Flux to calculate the average `temp` for blueberries in the `north` region: + +```js +// Schema 1 - Query for data encoded in the measurement name +from(bucket:"example-bucket") + |> range(start:2016-08-30T00:00:00Z) + |> filter(fn: (r) => r._measurement =~ /\.north$/ and r._field == "temp") + |> mean() + +// Schema 2 - Query for data encoded in tags +from(bucket:"example-bucket") + |> range(start:2016-08-30T00:00:00Z) + |> filter(fn: (r) => r._measurement == "weather_sensor" and r.region == "north" and r._field == "temp") + |> mean() +``` + +In schema 1, we see that querying the `plot` and `region` in the measurement name makes the data more difficult to query. + +### Avoid putting more than one piece of information in one tag + +Splitting a single tag with multiple pieces into separate tags simplifies your queries and reduces the need for regular expressions. + +#### Example line protocol schemas + +Consider the following schema represented by line protocol. + +``` +Schema 1 - Multiple data encoded in a single tag +------------- +weather_sensor,crop=blueberries,location=plot-1.north temp=50.1 1472515200000000000 +weather_sensor,crop=blueberries,location=plot-2.midwest temp=49.8 1472515200000000000 +``` + +The schema 1 data encodes multiple parameters, the `plot` and `region`, into a long tag value (`plot-1.north`). +Compare this to schema 2: + +``` +Schema 2 - Data encoded in multiple tags +------------- +weather_sensor,crop=blueberries,plot=1,region=north temp=50.1 1472515200000000000 +weather_sensor,crop=blueberries,plot=2,region=midwest temp=49.8 1472515200000000000 +``` + +Schema 2 is preferable because, with multiple tags, you don't need a regular expression. + +#### Flux example to query schemas + +The following Flux examples show how to calculate the average `temp` for blueberries in the `north` region; both for schema 1 and schema 2. + +```js +// Schema 1 - Query for multiple data encoded in a single tag +from(bucket:"example-bucket") + |> range(start:2016-08-30T00:00:00Z) + |> filter(fn: (r) => r._measurement == "weather_sensor" and r.location =~ /\.north$/ and r._field == "temp") + |> mean() + +// Schema 2 - Query for data encoded in multiple tags +from(bucket:"example-bucket") + |> range(start:2016-08-30T00:00:00Z) + |> filter(fn: (r) => r._measurement == "weather_sensor" and r.region == "north" and r._field == "temp") + |> mean() +``` +In schema 1, we see that querying the `plot` and `region` in a single tag makes the data more difficult to query. + + diff --git a/content/influxdb/v2.1/write-data/delete-data.md b/content/influxdb/v2.1/write-data/delete-data.md new file mode 100644 index 0000000000..5270bc3d7d --- /dev/null +++ b/content/influxdb/v2.1/write-data/delete-data.md @@ -0,0 +1,143 @@ +--- +title: Delete data +list_title: Delete data +description: > + Delete data in the InfluxDB CLI and API. +menu: + influxdb_2_1: + name: Delete data + parent: Write data +weight: 106 +influxdb/v2.1/tags: [delete] +related: + - /influxdb/v2.1/reference/syntax/delete-predicate/ + - /influxdb/v2.1/reference/cli/influx/delete/ +--- + + + +Use the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) or the InfluxDB API +[`/api/v2/delete`](/influxdb/v2.1/api/#operation/PostDelete) endpoint to delete data. + +- [Delete data using the influx CLI](#delete-data-using-the-influx-cli) +- [Delete data using the API](#delete-data-using-the-api) + + +## Delete data using the influx CLI + +{{% note %}} +Use [InfluxDB CLI connection configurations](/influxdb/v2.1/reference/cli/influx/config/) +to provide your **InfluxDB host, organization, and API token**. +{{% /note %}} + +1. Use the [`influx delete` command](/influxdb/v2.1/reference/cli/influx/delete/) to delete points from InfluxDB. +2. Use the `--bucket` flag to specify which bucket to delete data from. +3. Use the `--start` and `--stop` flags to define the time range to delete data from. + Use [RFC3339 timestamps](/influxdb/v2.1/reference/glossary/#rfc3339-timestamp). +4. _(Optional)_ Use the `-p`, `--predicate` flag to include a [delete predicate](/influxdb/v2.1/reference/syntax/delete-predicate) + that identifies which points to delete. + + {{% warn %}} +Deleting data without a [delete predicate](/influxdb/v2.1/reference/syntax/delete-predicate) +deletes all data in the specified bucket with timestamps between the specified `start` and `stop` times. + {{% /warn %}} + +### Examples + +##### Delete points in a specific measurement with a specific tag value +```sh +influx delete --bucket example-bucket \ +  --start '1970-01-01T00:00:00Z' \ +  --stop $(date +"%Y-%m-%dT%H:%M:%SZ") \ + --predicate '_measurement="example-measurement" AND exampleTag="exampleTagValue"' +``` + +##### Delete all points in a specified time range +```sh +influx delete --bucket example-bucket \ + --start 2020-03-01T00:00:00Z \ + --stop 2020-11-14T00:00:00Z +``` + +## Delete data using the API +Use the InfluxDB API [`/api/v2/delete` endpoint](/influxdb/v2.1/api/#operation/PostDelete) +to delete points from InfluxDB. +Include the following: + +- **Request method:** `POST` +- **Headers:** + - **Authorization:** `Token` schema with your InfluxDB API token + - **Content-type:** `application/json` +- **Query parameters:** + - **org** or **orgID:** organization name or [organization ID](/influxdb/v2.1/organizations/view-orgs/#view-your-organization-id) + - **bucket** or **bucketID:** bucket name or [bucket ID](/influxdb/v2.1/organizations/buckets/view-buckets/) +- **Request body:** JSON object with the following fields: + {{< req type="key" >}} + - {{< req "\*" >}} **start:** earliest time to delete data from ([RFC3339](/influxdb/v2.1/reference/glossary/#rfc3339-timestamp)) + - {{< req "\*" >}} **stop:** latest time to delete data from ([RFC3339](/influxdb/v2.1/reference/glossary/#rfc3339-timestamp)) + - **predicate:** [delete predicate](/influxdb/v2.1/reference/syntax/delete-predicate) statement + + {{% warn %}} +Deleting data without a [delete predicate](/influxdb/v2.1/reference/syntax/delete-predicate) +deletes all data in the specified bucket with timestamps between the specified `start` and `stop` times. + {{% /warn %}} + +#### Examples + +##### Delete points in a specific measurement with a specific tag value +```sh +curl --request POST http://localhost:8086/api/v2/delete?org=example-org&bucket=example-bucket \ + --header 'Authorization: Token YOUR_API_TOKEN' \ + --header 'Content-Type: application/json' \ + --data '{ + "start": "2020-03-01T00:00:00Z", + "stop": "2020-11-14T00:00:00Z", + "predicate": "_measurement=\"example-measurement\" AND exampleTag=\"exampleTagValue\"" + }' +``` + +##### Delete all points in a specified time range +```sh +curl --request POST http://localhost:8086/api/v2/delete?org=example-org&bucket=example-bucket \ + --header 'Authorization: Token YOUR_API_TOKEN' \ + --header 'Content-Type: application/json' \ + --data '{ + "start": "2020-03-01T00:00:00Z", + "stop": "2020-11-14T00:00:00Z" + }' +``` + +_For more information, see the [`/api/v2/delete` endpoint documentation](/influxdb/v2.1/api/#operation/PostDelete)._ diff --git a/content/influxdb/v2.1/write-data/developer-tools/_index.md b/content/influxdb/v2.1/write-data/developer-tools/_index.md new file mode 100644 index 0000000000..8c9a0c2707 --- /dev/null +++ b/content/influxdb/v2.1/write-data/developer-tools/_index.md @@ -0,0 +1,16 @@ +--- +title: Write data with developer tools +seotitle: Write data to InfluxDB with developer tools +list_title: Use developer tools +weight: 102 +description: > + Use developer tools such as the InfluxDB API and `influx` CLI to write data to InfluxDB. +menu: + influxdb_2_1: + name: Developer tools + parent: Write data +--- + +Write data to InfluxDB with developer tools. + +{{< children >}} diff --git a/content/influxdb/v2.1/write-data/developer-tools/api.md b/content/influxdb/v2.1/write-data/developer-tools/api.md new file mode 100644 index 0000000000..8fb5e2b669 --- /dev/null +++ b/content/influxdb/v2.1/write-data/developer-tools/api.md @@ -0,0 +1,57 @@ +--- +title: Write data with the InfluxDB API +weight: 206 +description: > + Use the `/write` endpoint of the InfluxDB API to write data to InfluxDB. +menu: + influxdb_2_1: + name: InfluxDB API + parent: Developer tools +--- +Write data to InfluxDB using an HTTP request to the InfluxDB API `/write` endpoint. +Use the `POST` request method and include the following in your request: + +| Requirement | Include by | +|:----------- |:---------- | +| Organization | Use the `org` query parameter in your request URL. | +| Bucket | Use the `bucket` query parameter in your request URL. | +| Timestamp precision | Use the [`precision`](/influxdb/v2.1/write-data/#timestamp-precision) query parameter in your request URL. Default is `ns`. | +| API token | Use the `Authorization: Token YOUR_API_TOKEN` header. | +| Line protocol | Pass as plain text in your request body. | + +#### Send a write request + +The URL in the examples depends on the version and location of your InfluxDB {{< current-version >}} instance. +Customize URLs in examples + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Curl](#curl) +[Node.js](#nodejs) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +{{< get-shared-text "api/v2.0/write/write.sh" >}} +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```js +{{< get-shared-text "api/v2.0/write/write.sh" >}} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% note %}} +##### Use gzip compression with the InfluxDB API + +When using the InfluxDB API `/write` endpoint to write data, compress the data with `gzip` and set the `Content-Encoding` +header to `gzip`. +Compression reduces network bandwidth, but increases server-side load. + +```sh +{{% get-shared-text "api/v2.0/write/write-compress.sh" %}} +``` +{{% /note %}} + +_For information about **InfluxDB API response codes**, see +[InfluxDB API Write documentation](/influxdb/v2.1/api/#operation/PostWrite)._ diff --git a/content/influxdb/v2.1/write-data/developer-tools/client-libraries.md b/content/influxdb/v2.1/write-data/developer-tools/client-libraries.md new file mode 100644 index 0000000000..77b06d5e96 --- /dev/null +++ b/content/influxdb/v2.1/write-data/developer-tools/client-libraries.md @@ -0,0 +1,15 @@ +--- +title: Write data with client libraries +weight: 204 +description: > + Use client libraries to write data to InfluxDB. +menu: + influxdb_2_1: + name: Client libraries + identifier: write-client-libraries + parent: Developer tools +--- + +Use language-specific client libraries to integrate with the InfluxDB v2 API. + +See [Client libraries reference](/influxdb/v2.1/api-guide/client-libraries/) for more information. diff --git a/content/influxdb/v2.1/write-data/developer-tools/csv.md b/content/influxdb/v2.1/write-data/developer-tools/csv.md new file mode 100644 index 0000000000..9bcb685a3b --- /dev/null +++ b/content/influxdb/v2.1/write-data/developer-tools/csv.md @@ -0,0 +1,596 @@ +--- +title: Write CSV data to InfluxDB +description: > + Write CSV data with the [`influx write` command](/influxdb/cloud/reference/cli/influx/write/) or Flux. + Include annotations with the CSV data to determine how the data translates into + [line protocol](/influxdb/v2.1/reference/syntax/line-protocol/). +menu: + influxdb_2_1: + name: Write CSV data + parent: Developer tools +aliases: + - /influxdb/v2.1/write-data/csv/ +weight: 204 +related: + - /influxdb/v2.1/reference/syntax/line-protocol/ + - /influxdb/v2.1/reference/syntax/annotated-csv/ + - /influxdb/v2.1/reference/cli/influx/write/ +--- + +Write CSV data with the following methods: + +- [Upload a file or manually paste data in the UI](/influxdb/cloud/write-data/no-code/load-data/#load-data-by-uploading-a-csv-or-line-protocol-file) +- [influx write command](#influx-write-command) +- [Telegraf](#telegraf) +- [Flux](#flux) + +## influx write command + +Use the [`influx write` command](/influxdb/v2.1/reference/cli/influx/write/) to write CSV data +to InfluxDB. Include [Extended annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv/extended/) +annotations to specify how the data translates into [line protocol](/influxdb/v2.1/reference/syntax/line-protocol/). +Include annotations in the CSV file or inject them using the `--header` flag of +the `influx write` command. + +##### On this page +- [CSV Annotations](#csv-annotations) +- [Inject annotation headers](#inject-annotation-headers) +- [Skip annotation headers](#skip-annotation-headers) +- [Process input as CSV](#process-input-as-csv) +- [Specify CSV character encoding](#specify-csv-character-encoding) +- [Skip rows with errors](#skip-rows-with-errors) +- [Advanced examples](#advanced-examples) + +##### Example write command +```sh +influx write -b example-bucket -f path/to/example.csv +``` + +##### example.csv +``` +#datatype measurement,tag,double,dateTime:RFC3339 +m,host,used_percent,time +mem,host1,64.23,2020-01-01T00:00:00Z +mem,host2,72.01,2020-01-01T00:00:00Z +mem,host1,62.61,2020-01-01T00:00:10Z +mem,host2,72.98,2020-01-01T00:00:10Z +mem,host1,63.40,2020-01-01T00:00:20Z +mem,host2,73.77,2020-01-01T00:00:20Z +``` + +##### Resulting line protocol +``` +mem,host=host1 used_percent=64.23 1577836800000000000 +mem,host=host2 used_percent=72.01 1577836800000000000 +mem,host=host1 used_percent=62.61 1577836810000000000 +mem,host=host2 used_percent=72.98 1577836810000000000 +mem,host=host1 used_percent=63.40 1577836820000000000 +mem,host=host2 used_percent=73.77 1577836820000000000 +``` + +{{% note %}} +To test the CSV to line protocol conversion process, use the `influx write dryrun` +command to print the resulting line protocol to stdout rather than write to InfluxDB. +{{% /note %}} + +{{% note %}} +##### "too many open files" errors + +When attempting to write large amounts of CSV data into InfluxDB, you might see an error like the following: + +``` +Error: Failed to write data: unexpected error writing points to database: [shard <#>] fcntl: too many open files. +``` + +To fix this error on Linux or macOS, run the following command to increase the number of open files allowed: + + ``` + ulimit -n 10000 + ``` + +macOS users, to persist the `ulimit` setting, follow the [recommended steps](https://unix.stackexchange.com/a/221988/471569) for your operating system version. + +{{% /note %}} + +## Telegraf + +Use CSV data format in Telegraf as a way to write CSV data to InfluxDB. + +For more information, see: + +- [CSV input data format](/telegraf/v1.19/data_formats/input/csv/) +- [Use Telegraf to write data](/influxdb/v2.1/write-data/no-code/use-telegraf/) + +## CSV Annotations +Use **CSV annotations** to specify which element of line protocol each CSV column +represents and how to format the data. CSV annotations are rows at the beginning +of a CSV file that describe column properties. + +The `influx write` command supports [Extended annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv/extended) +which provides options for specifying how CSV data should be converted into line +protocol and how data is formatted. + +To write data to InfluxDB, data must include the following: + +- [measurement](/influxdb/v2.1/reference/syntax/line-protocol/#measurement) +- [field set](/influxdb/v2.1/reference/syntax/line-protocol/#field-set) +- [timestamp](/influxdb/v2.1/reference/syntax/line-protocol/#timestamp) _(Optional but recommended)_ +- [tag set](/influxdb/v2.1/reference/syntax/line-protocol/#tag-set) _(Optional)_ + +Use CSV annotations to specify which of these elements each column represents. + +## Write raw query results back to InfluxDB +Flux returns query results in [annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv/). +These results include all annotations necessary to write the data back to InfluxDB. + +## Inject annotation headers +If the CSV data you want to write to InfluxDB does not contain the annotations +required to properly convert the data to line protocol, use the `--header` flag +to inject annotation rows into the CSV data. + +```sh +influx write -b example-bucket \ + -f path/to/example.csv \ + --header "#constant measurement,birds" \ + --header "#datatype dateTime:2006-01-02,long,tag" +``` + +{{< flex >}} +{{% flex-content %}} +##### example.csv +``` +date,sighted,loc +2020-01-01,12,Boise +2020-06-01,78,Boise +2020-01-01,54,Seattle +2020-06-01,112,Seattle +2020-01-01,9,Detroit +2020-06-01,135,Detroit +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +birds,loc=Boise sighted=12i 1577836800000000000 +birds,loc=Boise sighted=78i 1590969600000000000 +birds,loc=Seattle sighted=54i 1577836800000000000 +birds,loc=Seattle sighted=112i 1590969600000000000 +birds,loc=Detroit sighted=9i 1577836800000000000 +birds,loc=Detroit sighted=135i 1590969600000000000 +``` +{{% /flex-content %}} +{{< /flex >}} + +#### Use files to inject headers +The `influx write` command supports importing multiple files in a single command. +Include annotations and header rows in their own file and import them with the write command. +Files are read in the order in which they're provided. + +```sh +influx write -b example-bucket \ + -f path/to/headers.csv \ + -f path/to/example.csv +``` + +{{< flex >}} +{{% flex-content %}} +##### headers.csv +``` +#constant measurement,birds +#datatype dateTime:2006-01-02,long,tag +``` +{{% /flex-content %}} +{{% flex-content %}} +##### example.csv +``` +date,sighted,loc +2020-01-01,12,Boise +2020-06-01,78,Boise +2020-01-01,54,Seattle +2020-06-01,112,Seattle +2020-01-01,9,Detroit +2020-06-01,135,Detroit +``` +{{% /flex-content %}} +{{< /flex >}} + +##### Resulting line protocol +``` +birds,loc=Boise sighted=12i 1577836800000000000 +birds,loc=Boise sighted=78i 1590969600000000000 +birds,loc=Seattle sighted=54i 1577836800000000000 +birds,loc=Seattle sighted=112i 1590969600000000000 +birds,loc=Detroit sighted=9i 1577836800000000000 +birds,loc=Detroit sighted=135i 1590969600000000000 +``` + +## Skip annotation headers +Some CSV data may include header rows that conflict with or lack the annotations +necessary to write CSV data to InfluxDB. +Use the `--skipHeader` flag to specify the **number of rows to skip** at the +beginning of the CSV data. + +```sh +influx write -b example-bucket \ + -f path/to/example.csv \ + --skipHeader=2 +``` + +You can then [inject new header rows](#inject-annotation-headers) to rename columns +and provide the necessary annotations. + +## Process input as CSV +The `influx write` command automatically processes files with the `.csv` extension as CSV files. +If your CSV file uses a different extension, use the `--format` flat to explicitly +declare the format of the input file. + +```sh +influx write -b example-bucket \ + -f path/to/example.txt \ + --format csv +``` + +{{% note %}} +The `influx write` command assumes all input files are line protocol unless they +include the `.csv` extension or you declare the `csv`. +{{% /note %}} + +## Specify CSV character encoding +The `influx write` command assumes CSV files contain UTF-8 encoded characters. +If your CSV data uses different character encoding, specify the encoding +with the `--encoding`. + +```sh +influx write -b example-bucket \ + -f path/to/example.csv \ + --encoding "UTF-16" +``` + +## Skip rows with errors +If a row in your CSV data is missing an +[element required to write to InfluxDB](/influxdb/v2.1/reference/syntax/line-protocol/#elements-of-line-protocol) +or data is incorrectly formatted, when processing the row, the `influx write` command +returns an error and cancels the write request. +To skip rows with errors, use the `--skipRowOnError` flag. + +```sh +influx write -b example-bucket \ + -f path/to/example.csv \ + --skipRowOnError +``` + +{{% warn %}} +Skipped rows are ignored and are not written to InfluxDB. +{{% /warn %}} + +Use the `--errors-file` flag to record errors to a file. +The error file identifies all rows that cannot be imported and includes error messages for debugging. +For example: + +```error : line 3: column 'a': '1.1' cannot fit into long data type +cpu,1.1 +``` + +## Advanced examples + +- [Define constants](#define-constants) +- [Annotation shorthand](#annotation-shorthand) +- [Ignore columns](#ignore-columns) +- [Use alternate numeric formats](#use-alternate-numeric-formats) +- [Use alternate boolean format](#use-alternate-boolean-format) +- [Use different timestamp formats](#use-different-timestamp-formats) + +--- + +### Define constants +Use the Extended annotated CSV [`#constant` annotation](/influxdb/v2.1/reference/syntax/annotated-csv/extended/#constant) +to add a column and value to each row in the CSV data. + +{{< flex >}} +{{% flex-content %}} +##### CSV with constants +``` +#constant measurement,example +#constant tag,source,csv +#datatype long,dateTime:RFC3339 +count,time +1,2020-01-01T00:00:00Z +4,2020-01-02T00:00:00Z +9,2020-01-03T00:00:00Z +18,2020-01-04T00:00:00Z +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +example,source=csv count=1 1577836800000000000 +example,source=csv count=4 1577923200000000000 +example,source=csv count=9 1578009600000000000 +example,source=csv count=18 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} + +--- + +### Annotation shorthand +Extended annotated CSV supports [annotation shorthand](/influxdb/v2.1/reference/syntax/annotated-csv/extended/#annotation-shorthand), +which lets you define the **column label**, **datatype**, and **default value** in the column header. + +{{< flex >}} +{{% flex-content %}} +##### CSV with annotation shorthand +``` +m|measurement,count|long|0,time|dateTime:RFC3339 +example,1,2020-01-01T00:00:00Z +example,4,2020-01-02T00:00:00Z +example,,2020-01-03T00:00:00Z +example,18,2020-01-04T00:00:00Z +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +example count=1 1577836800000000000 +example count=4 1577923200000000000 +example count=0 1578009600000000000 +example count=18 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} + +#### Replace column header with annotation shorthand +It's possible to replace the column header row in a CSV file with annotation +shorthand without modifying the CSV file. +This lets you define column data types and default values while writing to InfluxDB. + +To replace an existing column header row with annotation shorthand: + +1. Use the `--skipHeader` flag to ignore the existing column header row. +2. Use the `--header` flag to inject a new column header row that uses annotation shorthand. + +{{% note %}} +`--skipHeader` is the same as `--skipHeader=1`. +{{% /note %}} + +```sh +influx write -b example-bucket \ + -f example.csv \ + --skipHeader + --header="m|measurement,count|long|0,time|dateTime:RFC3339" +``` + +{{< flex >}} +{{% flex-content %}} +##### Unmodified example.csv +``` +m,count,time +example,1,2020-01-01T00:00:00Z +example,4,2020-01-02T00:00:00Z +example,,2020-01-03T00:00:00Z +example,18,2020-01-04T00:00:00Z +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +example count=1i 1577836800000000000 +example count=4i 1577923200000000000 +example count=0i 1578009600000000000 +example count=18i 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} + +--- + +### Ignore columns +Use the Extended annotated CSV [`#datatype ignored` annotation](/influxdb/v2.1/reference/syntax/annotated-csv/extended/#ignored) +to ignore columns when writing CSV data to InfluxDB. + +{{< flex >}} +{{% flex-content %}} +##### CSV data with ignored column +``` +#datatype measurement,long,time,ignored +m,count,time,foo +example,1,2020-01-01T00:00:00Z,bar +example,4,2020-01-02T00:00:00Z,bar +example,9,2020-01-03T00:00:00Z,baz +example,18,2020-01-04T00:00:00Z,baz +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +m count=1i 1577836800000000000 +m count=4i 1577923200000000000 +m count=9i 1578009600000000000 +m count=18i 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} + +--- + +### Use alternate numeric formats +If your CSV data contains numeric values that use a non-default fraction separator (`.`) +or contain group separators, [define your numeric format](/influxdb/v2.1/reference/syntax/annotated-csv/extended/#double) +in the `double`, `long`, and `unsignedLong` datatype annotations. + +{{% note %}} +If your **numeric format separators** include a comma (`,`), wrap the column annotation in double +quotes (`""`) to prevent the comma from being parsed as a column separator or delimiter. +You can also [define a custom column separator](/influxdb/v2.1/reference/syntax/annotated-csv/extended/#define-custom-column-separator). +{{% /note %}} + +{{< tabs-wrapper >}} +{{% tabs %}} +[Floats](#) +[Integers](#) +[Uintegers](#) +{{% /tabs %}} +{{% tab-content %}} +{{< flex >}} +{{% flex-content %}} +##### CSV with non-default float values +``` +#datatype measurement,"double:.,",dateTime:RFC3339 +m,lbs,time +example,"1,280.7",2020-01-01T00:00:00Z +example,"1,352.5",2020-01-02T00:00:00Z +example,"1,862.8",2020-01-03T00:00:00Z +example,"2,014.9",2020-01-04T00:00:00Z +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +example lbs=1280.7 1577836800000000000 +example lbs=1352.5 1577923200000000000 +example lbs=1862.8 1578009600000000000 +example lbs=2014.9 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} +{{% /tab-content %}} + +{{% tab-content %}} +{{< flex >}} +{{% flex-content %}} +##### CSV with non-default integer values +``` +#datatype measurement,"long:.,",dateTime:RFC3339 +m,lbs,time +example,"1,280.0",2020-01-01T00:00:00Z +example,"1,352.0",2020-01-02T00:00:00Z +example,"1,862.0",2020-01-03T00:00:00Z +example,"2,014.9",2020-01-04T00:00:00Z +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +example lbs=1280i 1577836800000000000 +example lbs=1352i 1577923200000000000 +example lbs=1862i 1578009600000000000 +example lbs=2014i 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} +{{% /tab-content %}} + +{{% tab-content %}} +{{< flex >}} +{{% flex-content %}} +##### CSV with non-default uinteger values +``` +#datatype measurement,"unsignedLong:.,",dateTime:RFC3339 +m,lbs,time +example,"1,280.0",2020-01-01T00:00:00Z +example,"1,352.0",2020-01-02T00:00:00Z +example,"1,862.0",2020-01-03T00:00:00Z +example,"2,014.9",2020-01-04T00:00:00Z +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +example lbs=1280u 1577836800000000000 +example lbs=1352u 1577923200000000000 +example lbs=1862u 1578009600000000000 +example lbs=2014u 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +--- + +### Use alternate boolean format +Line protocol supports only [specific boolean values](/influxdb/v2.1/reference/syntax/line-protocol/#boolean). +If your CSV data contains boolean values that line protocol does not support, +[define your boolean format](/influxdb/v2.1/reference/syntax/annotated-csv/extended/#boolean) +in the `boolean` datatype annotation. + +{{< flex >}} +{{% flex-content %}} +##### CSV with non-default boolean values +``` +sep=; +#datatype measurement,"boolean:y,Y,1:n,N,0",dateTime:RFC3339 +m,verified,time +example,y,2020-01-01T00:00:00Z +example,n,2020-01-02T00:00:00Z +example,1,2020-01-03T00:00:00Z +example,N,2020-01-04T00:00:00Z +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +example verified=true 1577836800000000000 +example verified=false 1577923200000000000 +example verified=true 1578009600000000000 +example verified=false 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} + +--- + +### Use different timestamp formats +The `influx write` command automatically detects **RFC3339** and **number** formatted +timestamps when converting CSV to line protocol. +If using a different timestamp format, [define your timestamp format](/influxdb/v2.1/reference/syntax/annotated-csv/extended/#datetime) +in the `dateTime` datatype annotation. + +{{< flex >}} +{{% flex-content %}} +##### CSV with non-default timestamps +``` +#datatype measurement,dateTime:2006-01-02,field +m,time,lbs +example,2020-01-01,1280.7 +example,2020-01-02,1352.5 +example,2020-01-03,1862.8 +example,2020-01-04,2014.9 +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +example lbs=1280.7 1577836800000000000 +example lbs=1352.5 1577923200000000000 +example lbs=1862.8 1578009600000000000 +example lbs=2014.9 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} + +## Flux + +Use the [csv.from()](/{{< latest "flux" >}}/stdlib/csv/from/) and [to()](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/to/) Flux functions to write an annotated CSV to the bucket of your choice. + +{{< youtube wPKZ9i0DulQ >}} + +The experimental [csv.from()](/{{< latest "flux" >}}/stdlib/csv/from/) function lets you write CSV from a URL. +The example below writes [NOAA water sample data](/influxdb/v2.1/reference/sample-data/#noaa-water-sample-data) to an example `noaa` bucket in an example organization: + +```js +import "experimental/csv" + +csv.from(url: "https://influx-testdata.s3.amazonaws.com/noaa.csv") + |> to(bucket: "noaa", org: "example-org") +``` + +{{% note %}} +#### Required columns +To write data to InfluxDB with Flux, data must include the following columns: + +- `_time` +- `_measurement` +- `_field` +- `_value` +{{% /note %}} diff --git a/content/influxdb/v2.1/write-data/developer-tools/influx-cli.md b/content/influxdb/v2.1/write-data/developer-tools/influx-cli.md new file mode 100644 index 0000000000..336165a834 --- /dev/null +++ b/content/influxdb/v2.1/write-data/developer-tools/influx-cli.md @@ -0,0 +1,56 @@ +--- +title: Write data with the influx CLI +weight: 205 +description: > + Use the `influx write` command to write data to InfluxDB from the command line. +menu: + influxdb_2_1: + name: Influx CLI + parent: Developer tools +related: + - /influxdb/v2.1/write-data/developer-tools/csv/ +--- + +To write data from the command line, use the [`influx write` command](/influxdb/v2.1/reference/cli/influx/write/). +Include the following in your command: + +| Requirement | Include by | +|:----------- |:---------- | +| Organization | Use the `-o`,`--org`, or `--org-id` flags. | +| Bucket | Use the `-b`, `--bucket`, or `--bucket-id` flags. | +| Precision | Use the `-p`, `--precision` flag. | +| API token | Set the `INFLUX_TOKEN` environment variable or use the `t`, `--token` flag. | +| Data | Write data using **line protocol** or **annotated CSV**. Pass a file with the `-f`, `--file` flag. | + +_See [Line protocol](/influxdb/v2.1/reference/syntax/line-protocol/) and [Annotated CSV](/influxdb/v2.1/reference/syntax/annotated-csv)_ + +#### Example influx write commands + +##### Write a single line of line protocol +```sh +influx write \ + -b bucketName \ + -o orgName \ + -p s \ + 'myMeasurement,host=myHost testField="testData" 1556896326' +``` + +##### Write line protocol from a file +```sh +influx write \ + -b bucketName \ + -o orgName \ + -p s \ + --format=lp + -f /path/to/line-protocol.txt +``` + +##### Write annotated CSV from a file +```sh +influx write \ + -b bucketName \ + -o orgName \ + -p s \ + --format=csv + -f /path/to/data.csv +``` diff --git a/content/influxdb/v2.1/write-data/developer-tools/scrape-prometheus-metrics.md b/content/influxdb/v2.1/write-data/developer-tools/scrape-prometheus-metrics.md new file mode 100644 index 0000000000..4cfba667ae --- /dev/null +++ b/content/influxdb/v2.1/write-data/developer-tools/scrape-prometheus-metrics.md @@ -0,0 +1,105 @@ +--- +title: Scrape Prometheus metrics +seotitle: Scape Prometheus metrics into InfluxDB +weight: 205 +description: > + Use Telegraf, InfluxDB scrapers, or the `prometheus.scrape` Flux function to + scrape Prometheus-formatted metrics from an HTTP-accessible endpoint and store + them in InfluxDB. +menu: + influxdb_2_1: + name: Scrape Prometheus metrics + parent: Developer tools +related: + - /{{< latest "telegraf" >}}/plugins/#prometheus, Telegraf Prometheus input plugin + - /{{< latest "flux" >}}/prometheus/scrape-prometheus/, Scrape Prometheus metrics with Flux + - /{{< latest "flux" >}}/stdlib/experimental/prometheus/scrape/ + - /{{< latest "flux" >}}/prometheus/metric-types/ + - /influxdb/v2.1/reference/prometheus-metrics/ + - /influxdb/v2.1/write-data/no-code/scrape-data/ +influxdb/v2.1/tags: [prometheus, scraper] +--- + +Use [Telegraf](/{{< latest "telegraf" >}}/){{% oss-only %}}, [InfluxDB scrapers](/influxdb/v2.1/write-data/no-code/scrape-data/),{{% /oss-only %}} +or the [`prometheus.scrape` Flux function](/{{< latest "flux" >}}/stdlib/experimental/prometheus/scrape/) +to scrape Prometheus-formatted metrics from an HTTP-accessible endpoint and store them in InfluxDB. + +{{% oss-only %}} + +- [Use Telegraf](#use-telegraf) +- [Use an InfluxDB scraper](#use-an-influxdb-scraper) +- [Use prometheus.scrape()](#use-prometheusscrape) + +{{% /oss-only %}} +{{% cloud-only %}} + +- [Use Telegraf](#use-telegraf) +- [Use prometheus.scrape()](#use-prometheusscrape) + +{{% /cloud-only %}} + +## Use Telegraf +To use Telegraf to scrape Prometheus-formatted metrics from an HTTP-accessible +endpoint and write them to InfluxDB{{% cloud-only %}} Cloud{{% /cloud-only %}}, follow these steps: + +1. Add the [Prometheus input plugin](/{{< latest "telegraf" >}}/plugins/#prometheus) to your Telegraf configuration file. + 1. Set the `urls` to scrape metrics from. + 2. Set the `metric_version` configuration option to specify which + [metric parsing version](/influxdb/v2.1/reference/prometheus-metrics/) to use + _(version `2` is recommended)_. +2. Add the [InfluxDB v2 output plugin](/{{< latest "telegraf" >}}/plugins/#influxdb_v2) + to your Telegraf configuration file and configure it to to write to + InfluxDB{{% cloud-only %}} Cloud{{% /cloud-only %}}. + +##### Example telegraf.conf +```toml +# ... + +## Collect Prometheus formatted metrics +[[inputs.prometheus]] + urls = ["http://example.com/metrics"] + metric_version = 2 + +## Write Prometheus formatted metrics to InfluxDB +[[outputs.influxdb_v2]] + urls = ["http://localhost:8086"] + token = "$INFLUX_TOKEN" + organization = "example-org" + bucket = "example-bucket" + +# ... +``` + +{{% oss-only %}} + +## Use an InfluxDB scraper +InfluxDB scrapers automatically scrape Prometheus-formatted metrics from an +HTTP-accessible endpoint at a regular interval. +For information about setting up an InfluxDB scraper, see +[Scrape data using InfluxDB scrapers](/influxdb/v2.1/write-data/no-code/scrape-data/). + +{{% /oss-only %}} + +## Use prometheus.scrape() +To use the [`prometheus.scrape()` Flux function](/{{< latest "flux" >}}/stdlib/experimental/prometheus/scrape/) +to scrape Prometheus-formatted metrics from an HTTP-accessible endpoint and write +them to InfluxDB{{% cloud-only %}} Cloud{{% /cloud-only %}}, do the following in your Flux script: + +1. Import the [`experimental/prometheus` package](/{{< latest "flux" >}}/stdlib/experimental/prometheus/). +2. Use `prometheus.scrape()` and provide the URL to scrape metrics from. +3. Use [`to()`](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/to/) and specify the InfluxDB{{% cloud-only %}} Cloud{{% /cloud-only %}} bucket to write + the scraped metrics to. + +##### Example Flux script +```js +import "experimental/prometheus" + +prometheus.scrape(url: "http://example.com/metrics") + |> to(bucket: "example-bucket") +``` + +4. (Optional) To scrape Prometheus metrics at regular intervals using Flux, add your Flux +scraping script as an [InfluxDB task](/{{< latest "influxdb" >}}/process-data/). + +_For information about scraping Prometheus-formatted metrics with `prometheus.scrape()`, +see [Scrape Prometheus metrics with Flux](/{{< latest "flux" >}}/prometheus/scrape-prometheus/)._ diff --git a/content/influxdb/v2.1/write-data/developer-tools/third-party-solutions.md b/content/influxdb/v2.1/write-data/developer-tools/third-party-solutions.md new file mode 100644 index 0000000000..5ca04b21ca --- /dev/null +++ b/content/influxdb/v2.1/write-data/developer-tools/third-party-solutions.md @@ -0,0 +1,61 @@ +--- +title: Write data with third-party technologies +weight: 103 +description: > + Write data to InfluxDB using third-party developer tools. +aliases: +menu: + influxdb_2_1: + name: Third-party developer tools + parent: Developer tools +--- + +Configure third-party technologies to send line protocol directly to InfluxDB. + +## AWS Lambda via CloudFormation template + +Write to InfluxDB with AWS Lambda, Amazon Web Services' serverless offering. This example provides a CloudFormation template that collects earthquake from the [United States Geological Survey (USGS)](https://www.usgs.gov/) every hour and outputs it as line protocol into an InfluxDB bucket. + +The [template](https://influxdata-lambda.s3.amazonaws.com/GeoLambda.yml) contains the following sections: + +- Lines 1-20: Define variables that the template asks for when it's installed. +- Lines 21-120: Handle a quirk of Lambda deployments that requires the Lambda assets to be in your region before deployment. As there is no elegant workaround, these 100 lines create an S3 bucket in your account in the region you're creating the stack and copies in these resources. +- Lines 121-132: Define a role with basic permission to run the Lambda. +- Lines 133-144: Define a Python library layer. This layer packages the Python HTTP library, a Python S2 Geometry library, and the InfluxDB Python client library. +- Lines 145-165: Define the Lambda function, a short Python script zipped up in a file called `geo_lambda.zip`. +- Lines 166-188: Define an event rule with permission to run the Lambda every hour. + +### Deploy the template + +1. Log into your free AWS account and search for the CloudFormation service. Make sure you’re in the AWS region you want to deploy the Lambda to⁠. +2. Click **Create Stack**. +3. In the **Prerequisite - Prepare Template** section, select **Template is ready**. +4. In the **Specify template** section: + - Under **Template source**, select **Amazon S3 URL**. + - In the **Amazon S3 URL** field, enter the CloudFormation template URL: `https://influxdata-lambda.s3.amazonaws.com/GeoLambda.yml` +5. Click **Next**. +6. Enter a name in the **Stack name** field. +7. Enter the following InfluxDB details: + - Organization ID + - Bucket ID of the bucket the Lambda writes to + - Token with permission to write to the bucket + - InfluxDB URL +8. Do not alter or add to any other fields. Click **Next**. +9. Select the **I acknowledge that AWS CloudFormation might create IAM resources** check box. +10. Click **Create Stack**. + +After a few minutes, the stack deploys to your region. To view the new Lambda, select **Services > AWS Lambda**. On the Lambda functions page, you should see your new Lambda. The `CopyZipsFunction` is the helper copy function, and the `GeoPythonLambda` does the data collection and writing work: + +{{< img-hd src="/img/cloudformation1.png" alt="GeoPythonLambda data in InfluxDB" />}} + +### Verify your setup + +`GeoPythonLambda` should run every hour based on the AWS Rule we set up, but you should test and confirm it works. + +1. Click `GeoPythonLambda`, and then click **Test**. +2. The test requires an input definition, but this Lambda has no input requirements, so click through and save the default dataset. +3. If the test is successful, a green **Execution result: succeeded** message appears. + +With the data points written, when you log into your InfluxDB UI, you’ll be able to explore the geolocation earthquake data: + +{{< img-hd src="/img/cloudformation2.png" alt="GeoPythonLambda data in InfluxDB" />}} diff --git a/content/influxdb/v2.1/write-data/no-code/_index.md b/content/influxdb/v2.1/write-data/no-code/_index.md new file mode 100644 index 0000000000..1e9d7b8192 --- /dev/null +++ b/content/influxdb/v2.1/write-data/no-code/_index.md @@ -0,0 +1,17 @@ +--- +title: Write data to InfluxDB without coding +weight: 101 +description: > + Use existing tools to write data to InfluxDB without writing code. +aliases: + - /influxdb/v2.1/collect-data/advanced-telegraf + - /influxdb/v2.1/collect-data/use-telegraf +menu: + influxdb_2_1: + name: No-code solutions + parent: Write data +--- + +The following options let you write data to InfluxDB without writing any code. Some options require a minimal amount of configuration. + +{{< children >}} diff --git a/content/influxdb/v2.1/write-data/no-code/load-data.md b/content/influxdb/v2.1/write-data/no-code/load-data.md new file mode 100644 index 0000000000..5ccb87a6df --- /dev/null +++ b/content/influxdb/v2.1/write-data/no-code/load-data.md @@ -0,0 +1,79 @@ +--- +title: Load data from sources in the InfluxDB user interface (UI) +seotitle: Load data source in UI +list_title: Load data source in UI +weight: 101 +description: > + Load data from sources in the InfluxDB user interface (UI). Choose from popular client libraries (such as Python, Ruby, Scala, and more!) or load data with a Telegraf plugin (like MQTT Consumer, MySQL, File, and many more!). +menu: + influxdb_2_1: + name: Load data source in UI + parent: Write data +--- + +Load data from the following sources in the InfluxDB user interface (UI): + +- [CSV or line protocol file](#load-csv-or-line-protocol-in-ui) +- [Line protocol](#load-data-using-line-protocol) +- [Client libraries](#load-data-from-a-client-library-in-the-ui) +- [Telegraf plugins](#load-data-from-a-telegraf-plugin-in-the-ui) + +### Load CSV or line protocol in UI + +Load CSV or line protocol data by uploading a file or pasting the data manually into the UI. + +1. In the navigation menu on the left, click **Data (Load Data)** > **Sources**. + {{< nav-icon "data" >}} +2. Under **File Upload**, select the type of data to upload: + - **Annotated CSV**. Verify your CSV file follows the supported [annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/) syntax. + - **Line Protocol**. Verify your line protocol file adheres to the following conventions: + - Each line represents a data point. + - Each data point requires a: + - [*measurement*](/influxdb/cloud/reference/syntax/line-protocol/#measurement) + - [*field set*](/influxdb/cloud/reference/syntax/line-protocol/#field-set) + - (Optional) [*tag set*](/influxdb/cloud/reference/syntax/line-protocol/#tag-set) + - [*timestamp*](/influxdb/cloud/reference/syntax/line-protocol/#timestamp) + + For more information, see supported [line protocol](/influxdb/cloud/reference/syntax/line-protocol/) syntax. + +2. Select the bucket to write to. +4. Select the **Precision** in the dropdown menu. By default, the precision is set to nanoseconds. +5. Do one of the following: + - To upload file, drag and drop your file onto the UI, and then click **Write Data**. + - To enter data manually, select the **Enter Manually** tab, paste your data, and then click **Write Data**. + +### Load data from a client library in the UI + +1. In the navigation menu on the left, click **Data (Load Data)** > **Sources**. + {{< nav-icon "data" >}} +2. Do one of the following: + - Enter a specific client library to search for in the **Search data writing methods** field. + - Scroll down to browse available client libraries. +3. Click the client library to load data from. +4. Under **Code Sample Options**, you'll see a list of your InfluxDB [tokens](/influxdb/v2.1/reference/glossary/#token) and [buckets](/influxdb/v2.1/reference/glossary/#bucket). Select both an API token and a bucket to write your data to. The selected API token and bucket are automatically added to scripts on the page that you can use to initialize a client and write data. +5. Click the **Copy to Clipboard** buttons under a script to easily paste the script into your terminal or save the script to reuse for automation. +6. Run the scripts on the page to do the following as needed: + - Install the package, libraries, or client + - Write data + - Execute a Flux query + +### Load data from a Telegraf plugin in the UI + +1. In the navigation menu on the left, click **Data (Load Data)** > **Sources**. + {{< nav-icon "data" >}} +2. Do one of the following: + - Enter a specific Telegraf plugin to search for in the **Search data writing methods** field. + - Scroll down to **Telegraf Plugins** and browse available input plugins. +3. Click the plugin to load data from. The plugin details page opens. +4. Select one of the options from the **Use this plugin** dropdown: + - **Create a new configuration**: Enter a configuration name and select an output bucket, and then click **Continue Configuring**. + - **Add to an existing configuration**: Select an existing Telegraf configuration to add this plugin to, and then click **Add to Existing Config**. +5. Provide a **Telegraf Configuration Name** and an optional **Telegraf Configuration Description**. +6. Adjust configuration settings as needed. To find configuration settings for a specific plugin, see [Telegraf plugins](/telegraf/latest/plugins/). +7. Click **Save and Test**. +8. The **Test Your Configuration** page provides instructions for how to start + Telegraf using the generated configuration. + _See [Start Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/auto-config/#start-telegraf) below for detailed information about what each step does._ +9. Once Telegraf is running, click **Listen for Data** to confirm Telegraf is successfully sending data to InfluxDB. + Once confirmed, a **Connection Found!** message appears. +10. Click **Finish**. Your Telegraf configuration name and the associated bucket name appears in the list of Telegraf configurations. diff --git a/content/influxdb/v2.1/write-data/no-code/scrape-data/_index.md b/content/influxdb/v2.1/write-data/no-code/scrape-data/_index.md new file mode 100644 index 0000000000..60f2bfd0a9 --- /dev/null +++ b/content/influxdb/v2.1/write-data/no-code/scrape-data/_index.md @@ -0,0 +1,31 @@ +--- +title: Scrape data using InfluxDB scrapers +weight: 103 +description: > + Scrape data from InfluxDB instances or remote endpoints using InfluxDB scrapers. + Create a scraper in the InfluxDB UI to collect metrics from a specified target. +aliases: + - /influxdb/v2.1/collect-data/scraper-metrics-endpoint + - /influxdb/v2.1/collect-data/scrape-data + - /influxdb/v2.1/write-data/scrape-data + - /influxdb/v2.1/write-data/scrapable-endpoints +influxdb/v2.1/tags: [scraper] +menu: + influxdb_2_1: + name: Scrape data + parent: No-code solutions +--- + +InfluxDB scrapers collect data from specified targets at regular intervals, +then write the scraped data to an InfluxDB bucket. +Scrapers can collect data from any HTTP(S)-accessible endpoint that provides data +in the [Prometheus data format](https://prometheus.io/docs/instrumenting/exposition_formats/). + +{{% cloud %}} +Scrapers are not available in {{< cloud-name "short" >}}. +{{% /cloud %}} + + +The following articles provide information about creating and managing InfluxDB data scrapers: + +{{< children >}} diff --git a/content/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/_index.md b/content/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/_index.md new file mode 100644 index 0000000000..386b8d32ac --- /dev/null +++ b/content/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/_index.md @@ -0,0 +1,17 @@ +--- +title: Manage InfluxDB scrapers +description: Create, update, and delete InfluxDB data scrapers in the InfluxDB user interface. +aliases: + - /influxdb/v2.1/collect-data/scrape-data/manage-scrapers + - /influxdb/v2.1/write-data/scrape-data/manage-scrapers +menu: + influxdb_2_1: + name: Manage scrapers + parent: Scrape data +weight: 201 +influxdb/v2.1/tags: [scraper, prometheus] +--- + +The following articles walk through managing InfluxDB scrapers: + +{{< children >}} diff --git a/content/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/create-a-scraper.md b/content/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/create-a-scraper.md new file mode 100644 index 0000000000..aae83bbc4c --- /dev/null +++ b/content/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/create-a-scraper.md @@ -0,0 +1,31 @@ +--- +title: Create an InfluxDB scraper +list_title: Create a scraper +description: Create an InfluxDB scraper that collects data from InfluxDB or a remote endpoint. +aliases: + - /influxdb/v2.1/collect-data/scrape-data/manage-scrapers/create-a-scraper + - /influxdb/v2.1/write-data/scrape-data/manage-scrapers/create-a-scraper +menu: + influxdb_2_1: + name: Create a scraper + parent: Manage scrapers +weight: 301 +--- + +Create a new scraper in the InfluxDB user interface (UI). + +## Create a scraper in the InfluxDB UI +1. In the navigation menu on the left, select **Data** (**Load Data**) > **Scrapers**. + + {{< nav-icon "load data" >}} + +3. Click **{{< icon "plus" >}} Create Scraper**. +4. Enter a **Name** for the scraper. +5. Select a **Bucket** to store the scraped data. +6. Enter the **Target URL** to scrape. + The default URL value is `http://localhost:8086/metrics`, + which provides InfluxDB-specific metrics in the [Prometheus data format](https://prometheus.io/docs/instrumenting/exposition_formats/). +7. Click **Create**. + +The new scraper will begin scraping data after approximately 10 seconds, +then continue scraping in 10 second intervals. diff --git a/content/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/delete-a-scraper.md b/content/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/delete-a-scraper.md new file mode 100644 index 0000000000..4d983c307b --- /dev/null +++ b/content/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/delete-a-scraper.md @@ -0,0 +1,23 @@ +--- +title: Delete an InfluxDB scraper +list_title: Delete a scraper +description: Delete an InfluxDB scraper in the InfluxDB user interface. +aliases: + - /influxdb/v2.1/collect-data/scrape-data/manage-scrapers/delete-a-scraper + - /influxdb/v2.1/write-data/scrape-data/manage-scrapers/delete-a-scraper +menu: + influxdb_2_1: + name: Delete a scraper + parent: Manage scrapers +weight: 303 +--- + +Delete a scraper from the InfluxDB user interface (UI). + +## Delete a scraper from the InfluxDB UI +1. In the navigation menu on the left, select **Data** (**Load Data**) > **Scrapers**. + + {{< nav-icon "load data" >}} + +3. Hover over the scraper you want to delete and click the **{{< icon "delete" >}}** icon. +4. Click **Delete**. diff --git a/content/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/update-a-scraper.md b/content/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/update-a-scraper.md new file mode 100644 index 0000000000..9269fc912c --- /dev/null +++ b/content/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/update-a-scraper.md @@ -0,0 +1,28 @@ +--- +title: Update an InfluxDB scraper +list_title: Update a scraper +description: Update an InfluxDB scraper that collects data from InfluxDB or a remote endpoint. +aliases: + - /influxdb/v2.1/collect-data/scrape-data/manage-scrapers/update-a-scraper + - /influxdb/v2.1/write-data/scrape-data/manage-scrapers/update-a-scraper +menu: + influxdb_2_1: + name: Update a scraper + parent: Manage scrapers +weight: 302 +--- + +Update a scraper in the InfluxDB user interface (UI). + +{{% note %}} +Scraper **Target URLs** and **Buckets** cannot be updated. +To modify either, [create a new scraper](/influxdb/v2.1/write-data/no-code/scrape-data/manage-scrapers/create-a-scraper). +{{% /note %}} + +## Update a scraper in the InfluxDB UI +1. In the navigation menu on the left, select **Data** (**Load Data**) > **Scrapers**. + + {{< nav-icon "load data" >}} + +3. Hover over the scraper you would like to update and click the **{{< icon "pencil" >}}** that appears next to the scraper name. +4. Enter a new name for the scraper. Press Return or click out of the name field to save the change. diff --git a/content/influxdb/v2.1/write-data/no-code/scrape-data/scrapable-endpoints.md b/content/influxdb/v2.1/write-data/no-code/scrape-data/scrapable-endpoints.md new file mode 100644 index 0000000000..7ee9cf3c87 --- /dev/null +++ b/content/influxdb/v2.1/write-data/no-code/scrape-data/scrapable-endpoints.md @@ -0,0 +1,45 @@ +--- +title: Create scrapable endpoints +seotitle: Create scrapable endpoints for InfluxDB +description: > + InfluxDB scrapers can collect data from any HTTP(S)-accessible endpoint that + returns data in the Prometheus data format. + This article provides links to information about the Prometheus data format + and tools that generate Prometheus-formatted metrics. +aliases: + - /influxdb/v2.1/collect-data/scrape-data/scrapable-endpoints +menu: + influxdb_2_1: + parent: Scrape data +weight: 202 +influxdb/v2.1/tags: [scraper, prometheus] +--- + +InfluxDB scrapers can collect data from any HTTP(S)-accessible endpoint that returns data +in the [Prometheus data format](https://prometheus.io/docs/instrumenting/exposition_formats/). +The links below provide information about the Prometheus data format and tools +and clients that generate Prometheus-formatted metrics. + +## Prometheus Node Exporter +The [Prometheus Node Exporter](https://github.com/prometheus/node_exporter) exposes +a wide variety of hardware- and kernel-related metrics for **\*nix** systems. + +##### Helpful links +[Monitoring linux host metrics with the Node Exporter](https://prometheus.io/docs/guides/node-exporter/) + +## Prometheus exporters and integrations +[Prometheus exporters and integrations](https://prometheus.io/docs/instrumenting/exporters/) +export Prometheus metrics from third-party systems or services. + +##### Helpful links +[List of third-party exporters](https://prometheus.io/docs/instrumenting/exporters/#third-party-exporters) +[Write a custom Prometheus exporter](https://prometheus.io/docs/instrumenting/writing_exporters/) + +## Prometheus client libraries +[Prometheus client libraries](https://prometheus.io/docs/instrumenting/clientlibs/) +instrument applications for each of their respective languages. +Application metrics are output to an HTTP(S) endpoint where they can be scraped. + +##### Helpful links +[Instrumenting a Go application for Prometheus](https://prometheus.io/docs/guides/go-application/) +[Writing Prometheus client libraries](https://prometheus.io/docs/instrumenting/writing_clientlibs/) diff --git a/content/influxdb/v2.1/write-data/no-code/third-party.md b/content/influxdb/v2.1/write-data/no-code/third-party.md new file mode 100644 index 0000000000..5278212c93 --- /dev/null +++ b/content/influxdb/v2.1/write-data/no-code/third-party.md @@ -0,0 +1,92 @@ +--- +title: Write data with no-code third-party technologies +weight: 103 +description: > + Write data to InfluxDB using third-party technologies that do not require coding. +menu: + influxdb_2_1: + name: Third-party technologies + parent: No-code solutions +--- + + +A number of third-party technologies can be configured to send line protocol directly to InfluxDB. + + +If you're using any of the following technologies, check out the handy links below to configure these technologies to write data to InfluxDB (**no additional software to download or install**). + +{{% note %}} +Many third-party integrations are community contributions. If there's an integration missing from the list below, please [open a docs issue](https://github.com/influxdata/docs-v2/issues/new/choose) to let us know. +{{% /note %}} + +- (Write metrics and log events only) [Vector 0.9 or later](#configure-vector) + +- [Apache NiFi 1.8 or later](#configure-apache-nifi) + +- [OpenHAB 3.0 or later](#configure-openhab) + +- [Apache JMeter 5.2 or later](#configure-apache-jmeter) + +- [Apache Pulsar](#configure-apache-pulsar) + +- [FluentD 1.x or later](#configure-fluentd) + + +#### Configure Vector + +1. View the **Vector documentation**: + - For write metrics, [InfluxDB Metrics Sink](https://vector.dev/docs/reference/sinks/influxdb_metrics/) + - For log events, [InfluxDB Logs Sink](https://vector.dev/docs/reference/sinks/influxdb_logs/) +2. Under **Configuration**, click **v2** to view configuration settings. +3. Scroll down to **How It Works** for more detail: + - [InfluxDB Metrics Sink – How It Works ](https://vector.dev/docs/reference/sinks/influxdb_metrics/#how-it-works) + - [InfluxDB Logs Sink – How It Works](https://vector.dev/docs/reference/sinks/influxdb_logs/#how-it-works) + +#### Configure Apache NiFi + +See the _[InfluxDB Processors for Apache NiFi Readme](https://github.com/influxdata/nifi-influxdb-bundle#influxdb-processors-for-apache-nifi)_ for details. + +#### Configure OpenHAB + +See the _[InfluxDB Persistence Readme](https://github.com/openhab/openhab-addons/tree/master/bundles/org.openhab.persistence.influxdb)_ for details. + +#### Configure Apache JMeter + + + +To configure Apache JMeter, complete the following steps in InfluxDB and JMeter. + +##### In InfluxDB + +1. [Find the name of your organization](/influxdb/v2.1/organizations/view-orgs/) (needed to create a bucket and token). +2. [Create a bucket using the influx CLI](/influxdb/v2.1/organizations/buckets/create-bucket/#create-a-bucket-using-the-influx-cli) and name it `jmeter`. +3. [Create a token](/influxdb/v2.1/security/tokens/create-token/). + +##### In JMeter + +1. Create a [Backend Listener](https://jmeter.apache.org/usermanual/component_reference.html#Backend_Listener) using the _**InfluxDBBackendListenerClient**_ implementation. +2. In the **Backend Listener implementation** field, enter: + ``` + org.apache.jmeter.visualizers.backend.influxdb.influxdbBackendListenerClient + ``` +3. Under **Parameters**, specify the following: + - **influxdbMetricsSender**: + ``` + org.apache.jmeter.visualizers.backend.influxdb.HttpMetricsSender + ``` + - **influxdbUrl**: _(include the bucket and org you created in InfluxDB)_ + ``` + http://localhost:8086/api/v2/write?org=my-org&bucket=jmeter + ``` + - **application**: `InfluxDB2` + - **influxdbToken**: _your InfluxDB API token_ + - Include additional parameters as needed. +4. Click **Add** to add the _**InfluxDBBackendListenerClient**_ implementation. + +#### Configure Apache Pulsar + +See _[InfluxDB sink connector](https://pulsar.apache.org/docs/en/io-influxdb-sink/)_ for details. + +#### Configure FluentD + +See the _[influxdb-plugin-fluent Readme](https://github.com/influxdata/influxdb-plugin-fluent)_ for details. diff --git a/content/influxdb/v2.1/write-data/no-code/use-telegraf/_index.md b/content/influxdb/v2.1/write-data/no-code/use-telegraf/_index.md new file mode 100644 index 0000000000..356acf605c --- /dev/null +++ b/content/influxdb/v2.1/write-data/no-code/use-telegraf/_index.md @@ -0,0 +1,36 @@ +--- +title: Use Telegraf to write data +seotitle: Use the Telegraf agent to collect and write data +list_title: Use the Telegraf agent +weight: 101 +description: > + Use Telegraf to collect and write data to InfluxDB v2.1. + Create Telegraf configurations in the InfluxDB UI or manually configure Telegraf. +aliases: + - /influxdb/v2.1/collect-data/advanced-telegraf + - /influxdb/v2.1/collect-data/use-telegraf + - /influxdb/v2.1/write-data/use-telegraf/ +menu: + influxdb_2_1: + name: Telegraf (agent) + parent: No-code solutions +--- + +[Telegraf](https://www.influxdata.com/time-series-platform/telegraf/) is InfluxData's +data collection agent for collecting and reporting metrics. +Its vast library of input plugins and "plug-and-play" architecture lets you quickly +and easily collect metrics from many different sources. +This article describes how to use Telegraf to collect and store data in InfluxDB v2.1. + +For a list of available plugins, see [Telegraf plugins](/{{< latest "telegraf" >}}/plugins/). + +#### Requirements +- **Telegraf 1.9.2 or greater**. + _For information about installing Telegraf, see the + [Telegraf Installation instructions](/{{< latest "telegraf" >}}/introduction/installation/)._ + +## Configure Telegraf +Telegraf input and output plugins are enabled and configured in Telegraf's configuration file (`telegraf.conf`). +You have the following options for configuring Telegraf: + +{{< children >}} diff --git a/content/influxdb/v2.1/write-data/no-code/use-telegraf/auto-config.md b/content/influxdb/v2.1/write-data/no-code/use-telegraf/auto-config.md new file mode 100644 index 0000000000..96f58b6456 --- /dev/null +++ b/content/influxdb/v2.1/write-data/no-code/use-telegraf/auto-config.md @@ -0,0 +1,136 @@ +--- +title: Automatically configure Telegraf +seotitle: Automatically configure Telegraf for InfluxDB v2.1 +description: > + Use the InfluxDB UI to automatically generate a Telegraf configuration, + then start Telegraf using the generated configuration file. +aliases: + - /influxdb/v2.1/collect-data/use-telegraf/auto-config + - /influxdb/v2.1/write-data/use-telegraf/auto-config +menu: + influxdb_2_1: + parent: Telegraf (agent) +weight: 201 +related: + - /influxdb/v2.1/telegraf-configs/create/ +--- + +The InfluxDB user interface (UI) can automatically create Telegraf configuration files based on user-selected Telegraf plugins. +This article describes how to create a Telegraf configuration in the InfluxDB UI and +start Telegraf using the generated configuration file. + +{{< youtube M8KP7FAb2L0 >}} + +{{% note %}} +_View the [requirements](/influxdb/v2.1/write-data/no-code/use-telegraf#requirements) +for using Telegraf with InfluxDB v2.1._ +{{% /note %}} + +## Create a Telegraf configuration + +1. Open the InfluxDB UI _(default: [localhost:8086](http://localhost:8086))_. +2. In the navigation menu on the left, select **Data** (**Load Data**) > **Telegraf**. + + {{< nav-icon "load data" >}} + +4. Click **{{< icon "plus" >}} Create Configuration**. +5. In the **Bucket** dropdown, select the bucket where Telegraf will store collected data. +6. Select one or more of the available plugin groups and click **Continue**. +7. Review the list of **Plugins to Configure** for configuration requirements. + Plugins listed with a {{< icon "check" >}} + require no additional configuration. + To configure a plugin or access plugin documentation, click the plugin name. +5. Provide a **Telegraf Configuration Name** and an optional **Telegraf Configuration Description**. +6. Adjust configuration settings as needed. To find configuration settings for a specific plugin, see [Telegraf plugins](/telegraf/latest/plugins/). +7. Click **Save and Test**. +8. The **Test Your Configuration** page provides instructions for how to start Telegraf using the generated configuration. + _See [Start Telegraf](#start-telegraf) below for detailed information about what each step does._ +9. Once Telegraf is running, click **Listen for Data** to confirm Telegraf is successfully sending data to InfluxDB. + Once confirmed, a **Connection Found!** message appears. +10. Click **Finish**. Your Telegraf configuration name and the associated bucket name appears in the list of Telegraf configurations. + + +### Windows + +If you plan to monitor a Windows host using the System plugin, you must complete the following steps. + +1. In the list of Telegraf configurations, double-click your + Telegraf configuration, and then click **Download Config**. +2. Open the downloaded Telegraf configuration file and replace the `[[inputs.processes]]` plugin with one of the following Windows plugins, depending on your Windows configuration: + + - [`[[inputs.win_perf_counters]]`](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/win_perf_counters) + - [`[[inputs.win_services]]`](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/win_services) + +3. Save the file and place it in a directory that **telegraf.exe** can access. + + +## Start Telegraf + +Requests to the [InfluxDB v2 API](/influxdb/v2.1/reference/api/) must include an API token. +A token identifies specific permissions to the InfluxDB instance. + +### Configure your token as an environment variable + +1. Find your API token. _For information about viewing tokens, see [View tokens](/influxdb/v2.1/security/tokens/view-tokens/)._ + +2. To configure your API token as the `INFLUX_TOKEN` environment variable, run the command appropriate for your operating system and command-line tool: + +{{< tabs-wrapper >}} +{{% tabs %}} +[macOS or Linux](#) +[Windows](#) +{{% /tabs %}} + +{{% tab-content %}} +```sh +export INFLUX_TOKEN=YourAuthenticationToken +``` +{{% /tab-content %}} + +{{% tab-content %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[PowerShell](#) +[CMD](#) +{{% /code-tabs %}} + +{{% code-tab-content %}} +```sh +$env:INFLUX_TOKEN = "YourAuthenticationToken" +``` +{{% /code-tab-content %}} + +{{% code-tab-content %}} +```sh +set INFLUX_TOKEN=YourAuthenticationToken +# Make sure to include a space character at the end of this command. +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +### Start the Telegraf service + +Start the Telegraf service using the `-config` flag to specify the location of the generated Telegraf configuration file. + +- For Windows, the location is always a local file path. +- For Linux and macOS, the location can be a local file path or URL. + +Telegraf starts using the Telegraf configuration pulled from InfluxDB API. + +{{% note %}} +InfluxDB host URLs and ports differ between InfluxDB OSS and InfluxDB Cloud. +For the exact command, see the Telegraf configuration **Setup Instructions** in the InfluxDB UI. +{{% /note %}} + +```sh +telegraf -config http://localhost:8086/api/v2/telegrafs/0xoX00oOx0xoX00o +``` + +## Manage Telegraf configurations + +For more information about managing Telegraf configurations in InfluxDB, see +[Telegraf configurations](/influxdb/v2.1/telegraf-configs/). diff --git a/content/influxdb/v2.1/write-data/no-code/use-telegraf/manual-config.md b/content/influxdb/v2.1/write-data/no-code/use-telegraf/manual-config.md new file mode 100644 index 0000000000..5eba0b8424 --- /dev/null +++ b/content/influxdb/v2.1/write-data/no-code/use-telegraf/manual-config.md @@ -0,0 +1,161 @@ +--- +title: Manually configure Telegraf +seotitle: Manually configure Telegraf for InfluxDB v2.1 +description: > + Update existing or create new Telegraf configurations to use the `influxdb_v2` + output plugin to write to InfluxDB v2.1. + Start Telegraf using the custom configuration. +aliases: + - /influxdb/v2.1/collect-data/use-telegraf/manual-config + - /influxdb/v2.1/write-data/use-telegraf/manual-config +menu: + influxdb_2_1: + parent: Telegraf (agent) +weight: 202 +influxdb/v2.1/tags: [manually, plugin, mqtt] +related: + - /{{< latest "telegraf" >}}/plugins// + - /influxdb/v2.1/telegraf-configs/create/ + - /influxdb/v2.1/telegraf-configs/update/ +--- + +Use the Telegraf `influxdb_v2` output plugin to collect and write metrics into an InfluxDB v2.1 bucket. +This article describes how to enable the `influxdb_v2` output plugin in new and existing Telegraf configurations, +then start Telegraf using the custom configuration file. + +{{< youtube qFS2zANwIrc >}} + +{{% note %}} +_View the [requirements](/influxdb/v2.1/write-data/no-code/use-telegraf#requirements) +for using Telegraf with InfluxDB v2.1._ +{{% /note %}} + +## Configure Telegraf input and output plugins +Configure Telegraf input and output plugins in the Telegraf configuration file (typically named `telegraf.conf`). +Input plugins collect metrics. +Output plugins define destinations where metrics are sent. + +_See [Telegraf plugins](/{{< latest "telegraf" >}}/plugins//) for a complete list of available plugins._ + +### Manually add Telegraf plugins + +To manually add any of the available [Telegraf plugins](/{{< latest "telegraf" >}}/plugins//), follow the steps below. + +1. Find the plugin you want to enable from the complete list of available [Telegraf plugins](/{{< latest "telegraf" >}}/plugins//). +2. Click **View** to the right of the plugin name to open the plugin page on GitHub. For example, view the MQTT plugin GitHub page [here](https://github.com/influxdata/telegraf/blob/release-1.14/plugins/inputs/mqtt_consumer/README.md). +3. Copy and paste the example configuration into your Telegraf configuration file (typically named `telegraf.conf`). + +### Enable and configure the InfluxDB v2 output plugin + +To send data to an InfluxDB v2.1 instance, enable in the +[`influxdb_v2` output plugin](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb_v2/README.md) +in the `telegraf.conf`. + +To find an example InfluxDB v2 output plugin configuration in the UI: + +1. In the navigation menu on the left, select **Data (Load Data)** > **Telegraf**. + + {{< nav-icon "load data" >}} + +2. Click **InfluxDB Output Plugin**. +3. Click **Copy to Clipboard** to copy the example configuration or **Download Config** to save a copy. +4. Paste the example configuration into your `telegraf.conf` and specify the options below. + +The InfluxDB output plugin configuration contains the following options: + +##### urls +An array of URLs for your InfluxDB v2.1 instances. +See [InfluxDB URLs](/influxdb/v2.1/reference/urls/) for information about which URLs to use. +**{{< cloud-name "short">}} requires HTTPS**. + +##### token +Your InfluxDB v2.1 authorization token. +For information about viewing tokens, see [View tokens](/influxdb/v2.1/security/tokens/view-tokens/). + +{{% note %}} +###### Avoid storing tokens in `telegraf.conf` +We recommend storing your tokens by setting the `INFLUX_TOKEN` environment variable and including the environment variable in your configuration file. + +{{< tabs-wrapper >}} +{{% tabs %}} +[macOS or Linux](#) +[Windows](#) +{{% /tabs %}} + +{{% tab-content %}} +```sh +export INFLUX_TOKEN=YourAuthenticationToken +``` +{{% /tab-content %}} + +{{% tab-content %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[PowerShell](#) +[CMD](#) +{{% /code-tabs %}} + +{{% code-tab-content %}} +```sh +$env:INFLUX_TOKEN = "YourAuthenticationToken" +``` +{{% /code-tab-content %}} + +{{% code-tab-content %}} +```sh +set INFLUX_TOKEN=YourAuthenticationToken +# Make sure to include a space character at the end of this command. +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +_See the [example `telegraf.conf` below](#example-influxdb_v2-configuration)._ +{{% /note %}} + +##### organization +The name of the organization that owns the target bucket. + +##### bucket +The name of the bucket to write data to. + +#### Example influxdb_v2 configuration +The example below illustrates an `influxdb_v2` configuration. + +```toml +# ... + +[[outputs.influxdb_v2]] + urls = ["http://localhost:8086"] + token = "$INFLUX_TOKEN" + organization = "example-org" + bucket = "example-bucket" + +# ... +``` + +{{% note %}} +##### Write to InfluxDB v1.x and v2.1 +If a Telegraf agent is already writing to an InfluxDB v1.x database, +enabling the InfluxDB v2 output plugin will write data to both v1.x and v2.1 instances. +{{% /note %}} + +## Add a custom Telegraf configuration to InfluxDB +To add a custom or manually configured Telegraf configuration to your collection +of Telegraf configurations in InfluxDB, use the [`influx telegrafs create`](/influxdb/v2.1/reference/cli/influx/telegrafs/create/) +or [`influx telegrafs update`](/influxdb/v2.1/reference/cli/influx/telegrafs/update/) commands. +For more information, see: + +- [Create a Telegraf configuration](/influxdb/v2.1/telegraf-configs/create/#use-the-influx-cli) +- [Update a Telegraf configuration](/influxdb/v2.1/telegraf-configs/update/#use-the-influx-cli) + +## Start Telegraf + +Start the Telegraf service using the `--config` flag to specify the location of your `telegraf.conf`. + +```sh +telegraf --config /path/to/custom/telegraf.conf +``` diff --git a/content/influxdb/v2.1/write-data/no-code/use-telegraf/use-telegraf-plugins/_index.md b/content/influxdb/v2.1/write-data/no-code/use-telegraf/use-telegraf-plugins/_index.md new file mode 100644 index 0000000000..88862cf57f --- /dev/null +++ b/content/influxdb/v2.1/write-data/no-code/use-telegraf/use-telegraf-plugins/_index.md @@ -0,0 +1,16 @@ +--- +title: Use Telegraf plugins +description: > + Use Telegraf plugins to capture and write metrics to InfluxDB. +aliases: + - /influxdb/v2.1/write-data/use-telegraf/use-telegraf-plugins/ +menu: + influxdb_2_1: + name: Use Telegraf plugins + parent: Telegraf (agent) +weight: 202 +--- + +The following articles guide you through step-by-step Telegraf configuration examples: + +{{< children >}} diff --git a/content/influxdb/v2.1/write-data/no-code/use-telegraf/use-telegraf-plugins/use-http-plugin.md b/content/influxdb/v2.1/write-data/no-code/use-telegraf/use-telegraf-plugins/use-http-plugin.md new file mode 100644 index 0000000000..7e33a192cd --- /dev/null +++ b/content/influxdb/v2.1/write-data/no-code/use-telegraf/use-telegraf-plugins/use-http-plugin.md @@ -0,0 +1,119 @@ +--- +title: Use the HTTP input plugin +seotitle: Use the Telegraf HTTP input plugin to write data to InfluxDB +list_title: HTTP input plugin +description: > + Write Citi Bike data to your InfluxDB instance with the HTTP plugin. +aliases: + - /influxdb/v2.1/write-data/use-telegraf/use-telegraf-plugins/use-http-plugin/ +menu: + influxdb_2_1: + name: HTTP input plugin + parent: Use Telegraf plugins +weight: 202 +--- + +This example walks through using the Telegraf HTTP input plugin to collect live metrics on Citi Bike stations in New York City. Live station data is available in JSON format from [NYC OpenData](https://data.cityofnewyork.us/NYC-BigApps/Citi-Bike-Live-Station-Feed-JSON-/p94q-8hxh). + +Configure [`influxdb` output plugin](/{{< latest "telegraf" >}}/plugins//#influxdb) to write metrics to your InfluxDB {{< current-version >}} instance. + +## Configure the HTTP Input plugin in your Telegraf configuration file + +To retrieve data from the Citi Bike URL endpoint, enable the `inputs.http` input plugin in your Telegraf configuration file. + +Specify the following options: + +### `urls` +One or more URLs to read metrics from. For this example, use `https://gbfs.citibikenyc.com/gbfs/en/station_status.json`. + +### `data_format` +The format of the data in the HTTP endpoints that Telegraf will ingest. For this example, use JSON. + + +## Add parser information to your Telegraf configuration + +Specify the following JSON-specific options. + +### JSON + +#### `json_query` +To parse only the relevant portion of JSON data, set the `json_query` option with a [GJSON](https://github.com/tidwall/gjson) path. The result of the query should contain a JSON object or an array of objects. +In this case, we don't want to parse the JSON query's `executionTime` at the beginning of the data, so we'll limit this to include only the data in the `stationBeanList` array. + +#### `tag_keys` +List of one or more JSON keys that should be added as tags. For this example, we'll use the tag keys `id`, `stationName`, `city`, and `postalCode`. + +#### `json_string_fields` +List the keys of fields that are in string format so that they can be parsed as strings. Here, the string fields are `statusValue`, `stAddress1`, `stAddress2`, `location`, and `landMark`. + +#### `json_time_key` +Key from the JSON file that creates the timestamp metric. In this case, we want to use the time that station data was last reported, or the `lastCommunicationTime`. If you don't specify a key, the time that Telegraf reads the data becomes the timestamp. + +#### `json_time_format` +The format used to interpret the designated `json_time_key`. This example uses [Go reference time format](https://golang.org/pkg/time/#Time.Format). For example, `Mon Jan 2 15:04:05 MST 2006`. + +#### `json_timezone` +The timezone We'll set this to the Unix TZ value where our bike data takes place, `America/New_York`. + + +#### Example configuration + + ```toml + [[inputs.http]] + #URL for NYC's Citi Bike station data in JSON format + urls = ["https://feeds.citibikenyc.com/stations/stations.json"] + + #Overwrite measurement name from default `http` to `citibikenyc` + name_override = "citibikenyc" + + #Exclude url and host items from tags + tagexclude = ["url", "host"] + + #Data from HTTP in JSON format + data_format = "json" + + #Parse `stationBeanList` array only + json_query = "stationBeanList" + + #Set station metadata as tags + tag_keys = ["id", "stationName", "city", "postalCode"] + + #Do not include station landmark data as fields + fielddrop = ["landMark"] + + #JSON values to set as string fields + json_string_fields = ["statusValue", "stAddress1", "stAddress2", "location", "landMark"] + + #Latest station information reported at `lastCommunicationTime` + json_time_key = "lastCommunicationTime" + + #Time is reported in Golang "reference time" format + json_time_format = "2006-01-02 03:04:05 PM" + + #Time is reported in Eastern Standard Time (EST) + json_timezone = "America/New_York" + ``` + + + +## Start Telegraf and verify data appears + +[Start the Telegraf service](/telegraf/v1.14/introduction/getting-started/). + +To test that the data is being sent to InfluxDB, run the following (replacing `telegraf.conf` with the path to your configuration file): + +``` +telegraf -config ~/telegraf.conf -test +``` + +This command should return line protocol that looks similar to the following: + + +``` +citibikenyc,id=3443,stationName=W\ 52\ St\ &\ 6\ Ave statusKey=1,location="",totalDocks=41,availableDocks=32,latitude=40.76132983124814,longitude=-73.97982001304626,availableBikes=8,stAddress2="",stAddress1="W 52 St & 6 Ave",statusValue="In Service" 1581533519000000000 +citibikenyc,id=367,stationName=E\ 53\ St\ &\ Lexington\ Ave availableBikes=8,stAddress1="E 53 St & Lexington Ave",longitude=-73.97069431,latitude=40.75828065,stAddress2="",statusKey=1,location="",statusValue="In Service",totalDocks=34,availableDocks=24 1581533492000000000 +citibikenyc,id=359,stationName=E\ 47\ St\ &\ Park\ Ave totalDocks=64,availableBikes=15,statusValue="In Service",location="",latitude=40.75510267,availableDocks=49,stAddress1="E 47 St & Park Ave",longitude=-73.97498696,statusKey=1,stAddress2="" 1581533535000000000 +citibikenyc,id=304,stationName=Broadway\ &\ Battery\ Pl statusValue="In Service",availableDocks=11,stAddress1="Broadway & Battery Pl",statusKey=1,stAddress2="",location="",totalDocks=33,latitude=40.70463334,longitude=-74.01361706,availableBikes=22 1581533499000000000 +``` + +Now, you can explore and query the Citi Bike data in InfluxDB. diff --git a/content/influxdb/v2.1/write-data/troubleshoot.md b/content/influxdb/v2.1/write-data/troubleshoot.md new file mode 100644 index 0000000000..0e9b2282a7 --- /dev/null +++ b/content/influxdb/v2.1/write-data/troubleshoot.md @@ -0,0 +1,79 @@ +--- +title: Troubleshoot issues writing data +seotitle: Troubleshoot issues writing data +list_title: Troubleshoot issues writing data +weight: 106 > + Troubleshoot issues writing data. Find response codes for failed writes. Discover how writes fail, from exceeding rate or payload limits, to syntax errors and schema conflicts. +menu: + influxdb_2_1: + name: Troubleshoot issues + parent: Write data +influxdb/v2.1/tags: [write, line protocol, errors] +related: + - /influxdb/v2.1/api/#tag/Write, InfluxDB API /write endpoint + - /influxdb/v2.1/reference/internals + - /influxdb/v2.1/reference/cli/influx/write +--- +Learn how to handle and recover from errors when writing to InfluxDB. + +- [Discover common failure scenarios](#common-failure-scenarios) +- [HTTP status codes](#http-status-codes) +- [Troubleshoot failures](#troubleshoot-failures) + +## Common failure scenarios + +Write requests made to InfluxDB may fail for a number of reasons. +Common failure scenarios that return an HTTP `4xx` or `5xx` error status code include the following: + +- Request exceeded a rate limit. +- API token was invalid. +- Client or server reached a timeout threshold. +- Size of the data payload was too large. +- Data was not formatted correctly. + +Writes may fail partially or completely even though InfluxDB returns an HTTP `2xx` status code for a valid request. For example, a partial write may occur when InfluxDB writes all points that conform to the bucket schema, but rejects points that have the wrong data type in a field. + +## HTTP status codes + +InfluxDB uses conventional HTTP status codes to indicate the success or failure of a request. +Write requests return the following status codes: + +- `204` **Success**: InfluxDB validated the request data format and accepted the data for writing to the bucket. + {{% note %}} + `204` doesn't indicate a successful write operation since writes are asynchronous. + If some of your data did not write to the bucket, see how to [troubleshoot rejected points](#troubleshoot-rejected-points). + {{% /note %}} + +- `400` **Bad request**: The [line protocol](/influxdb/v2.1/reference/syntax/line-protocol/) data in the request was malformed. + The response body contains the first malformed line in the data. All request data was rejected and not written. +- `401` **Unauthorized**: May indicate one of the following: + - [`Authorization: Token` header](/influxdb/v2.1/api-guide/api_intro/#authentication) is missing or malformed. + - [API token](/influxdb/v2.1/api-guide/api_intro/#authentication) value is missing from the header. + - API token does not have sufficient permissions to write to the organization and the bucket. For more information about token types and permissions, see [Manage API tokens](/influxdb/v2.1/security/tokens/) +- `404` **Not found**: A requested resource (e.g. an organization or bucket) was not found. The response body contains the requested resource type, e.g. "organization", and resource name. +- `413` **Request entity too large**: All request data was rejected and not written. InfluxDB OSS only returns this error if the [Go (golang) `ioutil.ReadAll()`](https://pkg.go.dev/io/ioutil#ReadAll) function raises an error. +- `500` **Internal server error**: Default HTTP status for an error. +- `503` **Service unavailable**: Server is temporarily unavailable to accept writes. The `Retry-After` header describes when to try the write again. + +The `message` property of the response body may contain additional details about the error. + +## Troubleshoot failures + +If you notice data is missing in your bucket, do the following: + +- Check the `message` property in the response body for details about the error +- Verify all lines contain valid syntax, e.g. [line protocol](/influxdb/v2.1/reference/syntax/line-protocol/) or [CSV](/influxdb/v2.1/reference/syntax/annotated-csv/) +- Verify the data types match other data points with the same series. + For example, did you attempt to write `string` data to an `int` field? +- Verify the timestamps match the [precision parameter](/influxdb/v2.1/write-data/#timestamp-precision). +- Minimize payload size and network errors by [optimizing writes](/influxdb/v2.1/write-data/best-practices/optimize-writes/) + +### Troubleshoot rejected points + +InfluxDB may reject points even if the HTTP request returns "Success". +If some of your data did not write to the bucket, check for [field type](/influxdb/v2.1/reference/key-concepts/data-elements/#field-value) differences between the missing data point and other points that have the same [series](/influxdb/v2.1/reference/key-concepts/data-elements/#series). +For example, did you attempt to write `string` data to an `int` field? + +InfluxDB rejects points for the following reasons: +- The **batch** contains another point with the same series, but one of the fields has a different value type. +- The **bucket** contains another point with the same series, but one of the fields has a different value type. diff --git a/data/influxd_flags.yml b/data/influxd_flags.yml new file mode 100644 index 0000000000..a8c52398ad --- /dev/null +++ b/data/influxd_flags.yml @@ -0,0 +1,212 @@ +# List of all influxd flags used to build flag lists with links to the influxd +# configuration options documentation. +# +# - flag: "--flag-name" +# added: InfluxDB minor version the flag was added +# nolink: Do not create a link to the config options doc for this flag +# + +- flag: "--assets-path" + added: 2.0 + +- flag: "--bolt-path" + added: 2.0 + +- flag: "--e2e-testing" + added: 2.0 + +- flag: "--engine-path" + added: 2.0 + +- flag: "--feature-flags" + added: 2.0 + +- flag: "--flux-log-enabled" + added: 2.0 + +- flag: "-h, --help" + added: 2.0 + nolink: true + +- flag: "--http-bind-address" + added: 2.0 + +- flag: "--http-idle-timeout" + added: 2.0 + +- flag: "--http-read-header-timeout" + added: 2.0 + +- flag: "--http-read-timeout" + added: 2.0 + +- flag: "--http-write-timeout" + added: 2.0 + +- flag: "--influxql-max-select-buckets" + added: 2.0 + +- flag: "--influxql-max-select-point" + added: 2.0 + +- flag: "--influxql-max-select-series" + added: 2.0 + +- flag: "--log-level" + added: 2.0 + +- flag: "--metrics-disabled" + added: 2.0 + +- flag: "--nats-max-payload-bytes" + added: 2.0 + +- flag: "--nats-port" + added: 2.0 + +- flag: "--no-tasks" + added: 2.0 + +- flag: "--pprof-disabled" + added: 2.0 + +- flag: "--query-concurrency" + added: 2.0 + +- flag: "--query-initial-memory-bytes" + added: 2.0 + +- flag: "--query-max-memory-bytes" + added: 2.0 + +- flag: "--query-memory-bytes" + added: 2.0 + +- flag: "--query-queue-size" + added: 2.0 + +- flag: "--reporting-disabled" + added: 2.0 + +- flag: "--secret-store" + added: 2.0 + +- flag: "--session-length" + added: 2.0 + +- flag: "--session-renew-disabled" + added: 2.0 + +- flag: "--sqlite-path" + added: 2.1 + +- flag: "--storage-cache-max-memory-size" + added: 2.0 + +- flag: "--storage-cache-snapshot-memory-size" + added: 2.0 + +- flag: "--storage-cache-snapshot-write-cold-duration" + added: 2.0 + +- flag: "--storage-compact-full-write-cold-duration" + added: 2.0 + +- flag: "--storage-compact-throughput-burst" + added: 2.0 + +- flag: "--storage-max-concurrent-compactions" + added: 2.0 + +- flag: "--storage-max-index-log-file-size" + added: 2.0 + +- flag: "--storage-no-validate-field-size" + added: 2.1 + +- flag: "--storage-retention-check-interval" + added: 2.0 + +- flag: "--storage-series-file-max-concurrent-snapshot-compactions" + added: 2.0 + +- flag: "--storage-series-id-set-cache-size" + added: 2.0 + +- flag: "--storage-shard-precreator-advance-period" + added: 2.0 + +- flag: "--storage-shard-precreator-check-interval" + added: 2.0 + +- flag: "--storage-tsm-use-madv-willneed" + added: 2.0 + +- flag: "--storage-validate-keys" + added: 2.0 + +- flag: "--storage-wal-fsync-delay" + added: 2.0 + +- flag: "--storage-wal-max-concurrent-writes" + added: 2.1 + +- flag: "--storage-wal-max-write-delay" + added: 2.1 + +- flag: "--storage-write-timeout" + added: 2.1 + +- flag: "--store" + added: 2.0 + +- flag: "--testing-always-allow-setup" + added: 2.0 + +- flag: "--tls-cert" + added: 2.0 + +- flag: "--tls-key" + added: 2.0 + +- flag: "--tls-min-version" + added: 2.0 + +- flag: "--tls-strict-ciphers" + added: 2.0 + +- flag: "--tracing-type" + added: 2.0 + +- flag: "--ui-disabled" + added: 2.0 + +- flag: "--vault-addr" + added: 2.0 + +- flag: "--vault-cacert" + added: 2.0 + +- flag: "--vault-capath" + added: 2.0 + +- flag: "--vault-client-cert" + added: 2.0 + +- flag: "--vault-client-key" + added: 2.0 + +- flag: "--vault-client-timeout" + added: 2.0 + +- flag: "--vault-max-retries" + added: 2.0 + +- flag: "--vault-skip-verify" + added: 2.0 + +- flag: "--vault-tls-server-name" + added: 2.0 + +- flag: "--vault-token" + added: 2.0 diff --git a/data/products.yml b/data/products.yml index cd4d0cf138..c694798713 100644 --- a/data/products.yml +++ b/data/products.yml @@ -3,10 +3,11 @@ influxdb: altname: InfluxDB OSS namespace: influxdb list_order: 2 - versions: [v1.3, v1.4, v1.5, v1.6, v1.7, v1.8, v2.0] - latest: v2.0 - latest_override: v2.0 + versions: [v1.3, v1.4, v1.5, v1.6, v1.7, v1.8, v2.0, v2.1] + latest: v2.1 + latest_override: v2.1 latest_patches: + "2.1": 0 "2.0": 9 "1.8": 10 "1.7": 11 @@ -15,7 +16,8 @@ influxdb: "1.4": 3 "1.3": 9 latest_cli: - "2.0": 2.1.0 + "2.1": 2.2.0 + "2.0": 2.2.0 influxdb_cloud: name: InfluxDB Cloud diff --git a/deploy/edge.js b/deploy/edge.js index b5b58a5ef0..70e369bc31 100644 --- a/deploy/edge.js +++ b/deploy/edge.js @@ -3,8 +3,8 @@ const path = require('path'); const latestVersions = { - 'influxdb': 'v2.0', - 'influxdbv2': 'v2.0', + 'influxdb': 'v2.1', + 'influxdbv2': 'v2.1', 'telegraf': 'v1.20', 'chronograf': 'v1.9', 'kapacitor': 'v1.6', diff --git a/layouts/index.html b/layouts/index.html index b7d3ae8fc1..d84830b618 100644 --- a/layouts/index.html +++ b/layouts/index.html @@ -14,7 +14,7 @@
    {{ partial "svgs/homepage-hero.svg" }}
    -

    InfluxDB Cloud &
    InfluxDB OSS {{ replaceRE "v" "" $influxdbVersionV2 }}

    +

    InfluxDB Cloud &
    InfluxDB OSS 2.x

    The most powerful time series database. Designed to handle high write and query loads. diff --git a/layouts/partials/article.html b/layouts/partials/article.html index e9a4f28aea..a3522bcbf6 100644 --- a/layouts/partials/article.html +++ b/layouts/partials/article.html @@ -3,6 +3,7 @@

    {{ .Title }}

    {{ partial "article/supported-versions.html" . }} + {{ partial "article/page-meta.html" . }}
    {{ partial "article/stable-version.html" . }} {{ partial "article/flux-experimental.html" . }} diff --git a/layouts/partials/article/page-meta.html b/layouts/partials/article/page-meta.html new file mode 100644 index 0000000000..f49be29a4a --- /dev/null +++ b/layouts/partials/article/page-meta.html @@ -0,0 +1,8 @@ +{{ if .Page.Params.metadata }} +{{ range .Page.Params.metadata }} +

    {{ . | markdownify }}

    +{{ end }} +{{ end }} +{{ if .Page.Params.updated_in }} +

    Updated in {{ .Page.Params.updated_in }}

    +{{ end }} \ No newline at end of file diff --git a/layouts/partials/header/google-fonts.html b/layouts/partials/header/google-fonts.html index 550b505c82..ad66673430 100644 --- a/layouts/partials/header/google-fonts.html +++ b/layouts/partials/header/google-fonts.html @@ -1 +1,3 @@ - + + + \ No newline at end of file diff --git a/layouts/partials/topnav.html b/layouts/partials/topnav.html index 41e4168a8d..6ff7f019af 100644 --- a/layouts/partials/topnav.html +++ b/layouts/partials/topnav.html @@ -17,9 +17,9 @@
    - - - + + +
    diff --git a/layouts/shortcodes/caps.html b/layouts/shortcodes/caps.html new file mode 100644 index 0000000000..b048e47b1c --- /dev/null +++ b/layouts/shortcodes/caps.html @@ -0,0 +1 @@ +{{ .Inner }} \ No newline at end of file diff --git a/layouts/shortcodes/cli/influxd-flags.html b/layouts/shortcodes/cli/influxd-flags.html new file mode 100644 index 0000000000..a74f742303 --- /dev/null +++ b/layouts/shortcodes/cli/influxd-flags.html @@ -0,0 +1,12 @@ +{{- $productPathData := findRE "[^/]+.*?" .Page.RelPermalink -}} +{{- $currentVersion := replaceRE "v" "" (index $productPathData 1) -}} +{{- $flags := .Site.Data.influxd_flags -}} + +
      + {{ range $flags }} + {{ $flagAnchor := replaceRE "--" "#" .flag }} + {{ if ge (float $currentVersion) .added }} +
    • {{ if .nolink }}{{ .flag }}{{ else }}{{ .flag }}{{ end }}
      • + {{ end }} + {{ end }} +
    diff --git a/layouts/shortcodes/cli/influxd-flags.md b/layouts/shortcodes/cli/influxd-flags.md deleted file mode 100644 index f21476399f..0000000000 --- a/layouts/shortcodes/cli/influxd-flags.md +++ /dev/null @@ -1,56 +0,0 @@ -- [\--assets-path](/influxdb/v2.0/reference/config-options/#assets-path) -- [\--bolt-path](/influxdb/v2.0/reference/config-options/#bolt-path) -- [\--e2e-testing](/influxdb/v2.0/reference/config-options/#e2e-testing) -- [\--engine-path](/influxdb/v2.0/reference/config-options/#engine-path) -- -h, \-\-help -- [\--http-bind-address](/influxdb/v2.0/reference/config-options/#http-bind-address) -- [\--http-idle-timeout](/influxdb/v2.0/reference/config-options/#http-idle-timeout) -- [\--http-read-header-timeout](/influxdb/v2.0/reference/config-options/#http-read-header-timeout) -- [\--http-read-timeout](/influxdb/v2.0/reference/config-options/#http-read-timeout) -- [\--http-write-timeout](/influxdb/v2.0/reference/config-options/#http-write-timeout) -- [\--influxql-max-select-buckets](/influxdb/v2.0/reference/config-options/#influxql-max-select-buckets) -- [\--influxql-max-select-point](/influxdb/v2.0/reference/config-options/#influxql-max-select-point) -- [\--influxql-max-select-series](/influxdb/v2.0/reference/config-options/#influxql-max-select-series) -- [\--log-level](/influxdb/v2.0/reference/config-options/#log-level) -- [\--metrics-disabled](/influxdb/v2.0/reference/config-options/#metrics-disabled) -- [\--nats-max-payload-bytes](/influxdb/v2.0/reference/config-options/#nats-max-payload-bytes) -- [\--nats-port](/influxdb/v2.0/reference/config-options/#nats-port) -- [\--no-tasks](/influxdb/v2.0/reference/config-options/#no-tasks) -- [\--pprof-disabled](/influxdb/v2.0/reference/config-options/#pprof-disabled) -- [\--query-concurrency](/influxdb/v2.0/reference/config-options/#query-concurrency) -- [\--query-initial-memory-bytes](/influxdb/v2.0/reference/config-options/#query-initial-memory-bytes) -- [\--query-max-memory-bytes](/influxdb/v2.0/reference/config-options/#query-max-memory-bytes) -- [\--query-memory-bytes](/influxdb/v2.0/reference/config-options/#query-memory-bytes) -- [\--query-queue-size](/influxdb/v2.0/reference/config-options/#query-queue-size) -- [\--reporting-disabled](/influxdb/v2.0/reference/config-options/#reporting-disabled) -- [\--secret-store](/influxdb/v2.0/reference/config-options/#secret-store) -- [\--session-length](/influxdb/v2.0/reference/config-options/#session-length) -- [\--session-renew-disabled](/influxdb/v2.0/reference/config-options/#session-renew-disabled) -- [\--storage-cache-max-memory-size](/influxdb/v2.0/reference/config-options/#storage-cache-max-memory-size) -- [\--storage-cache-snapshot-memory-size](/influxdb/v2.0/reference/config-options/#storage-cache-snapshot-memory-size) -- [\--storage-cache-snapshot-write-cold-duration](/influxdb/v2.0/reference/config-options/#storage-cache-snapshot-write-cold-duration) -- [\--storage-compact-full-write-cold-duration](/influxdb/v2.0/reference/config-options/#storage-compact-full-write-cold-duration) -- [\--storage-compact-throughput-burst](/influxdb/v2.0/reference/config-options/#storage-compact-throughput-burst) -- [\--storage-max-concurrent-compactions](/influxdb/v2.0/reference/config-options/#storage-max-concurrent-compactions) -- [\--storage-max-index-log-file-size](/influxdb/v2.0/reference/config-options/#storage-max-index-log-file-size) -- [\--storage-retention-check-interval](/influxdb/v2.0/reference/config-options/#storage-retention-check-interval) -- [\--storage-series-file-max-concurrent-snapshot-compactions](/influxdb/v2.0/reference/config-options/#storage-series-file-max-concurrent-snapshot-compactions) -- [\--storage-series-id-set-cache-size](/influxdb/v2.0/reference/config-options/#storage-series-id-set-cache-size) -- [\--storage-shard-precreator-advance-period](/influxdb/v2.0/reference/config-options/#storage-shard-precreator-advance-period) -- [\--storage-shard-precreator-check-interval](/influxdb/v2.0/reference/config-options/#storage-shard-precreator-check-interval) -- [\--storage-tsm-use-madv-willneed](/influxdb/v2.0/reference/config-options/#storage-tsm-use-madv-willneed) -- [\--storage-validate-keys](/influxdb/v2.0/reference/config-options/#storage-validate-keys) -- [\--storage-wal-fsync-delay](/influxdb/v2.0/reference/config-options/#storage-wal-fsync-delay) -- [\--store](/influxdb/v2.0/reference/config-options/#store) -- [\--testing-always-allow-setup](/influxdb/v2.0/reference/config-options/#testing-always-allow-setup) -- [\--tls-cert](/influxdb/v2.0/reference/config-options/#tls-cert) -- [\--tls-key](/influxdb/v2.0/reference/config-options/#tls-key) -- [\--tls-min-version](/influxdb/v2.0/reference/config-options/#tls-min-version) -- [\--tls-strict-ciphers](/influxdb/v2.0/reference/config-options/#tls-strict-ciphers) -- [\--tracing-type](/influxdb/v2.0/reference/config-options/#tracing-type) -- [\--vault-client-key](/influxdb/v2.0/reference/config-options/#vault-client-key) -- [\--vault-client-timeout](/influxdb/v2.0/reference/config-options/#vault-client-timeout) -- [\--vault-max-retries](/influxdb/v2.0/reference/config-options/#vault-max-retries) -- [\--vault-skip-verify](/influxdb/v2.0/reference/config-options/#vault-skip-verify) -- [\--vault-tls-server-name](/influxdb/v2.0/reference/config-options/#vault-tls-server-name) -- [\--vault-token](/influxdb/v2.0/reference/config-options/#vault-token) diff --git a/layouts/shortcodes/current-version.html b/layouts/shortcodes/current-version.html new file mode 100644 index 0000000000..864b093cbf --- /dev/null +++ b/layouts/shortcodes/current-version.html @@ -0,0 +1,3 @@ +{{- $productPathData := findRE "[^/]+.*?" .Page.RelPermalink -}} +{{- $currentVersion := replaceRE "v" "" (index $productPathData 1) -}} +{{ $currentVersion }} \ No newline at end of file diff --git a/layouts/shortcodes/expand.html b/layouts/shortcodes/expand.html index 25dc47c776..6609f388f3 100644 --- a/layouts/shortcodes/expand.html +++ b/layouts/shortcodes/expand.html @@ -2,7 +2,7 @@ {{ $expandLabel := .Get 0 }}

    - {{ $expandLabel }} + {{ $expandLabel | safeHTML }}