From dddd911fe608b00f3d9448673981291a8f066c38 Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Fri, 11 Oct 2019 10:54:48 -0700 Subject: [PATCH 1/3] Revise "Write Data" guide --- content/v2.0/write-data/_index.md | 242 ++++++++++++++---------------- 1 file changed, 115 insertions(+), 127 deletions(-) diff --git a/content/v2.0/write-data/_index.md b/content/v2.0/write-data/_index.md index 6f85401a1..6b6fc3d30 100644 --- a/content/v2.0/write-data/_index.md +++ b/content/v2.0/write-data/_index.md @@ -11,38 +11,43 @@ menu: v2.0/tags: [write, line protocol] --- -Collect and write time series data to InfluxDB using [line protocol](/v2.0/reference/line-protocol), -Telegraf, data scrapers, the InfluxDB v2 API, `influx` command line interface (CLI), -the InfluxDB user interface (UI), and client libraries. - -- [Requirements to write data](#requirements-to-write-data) -- [InfluxDB v2 API](#write-data-using-the-influxdb-v2-api) -- [influx CLI](#write-data-using-the-influx-cli) -- [InfluxDB UI](#write-data-in-the-influxdb-ui) +- [What you'll need](#what-you-ll-need) +- [Ways to write data into InfluxDB](#ways-to-write-data-into-influxdb) + - [User Interface](#user-interface) + - [influx CLI](#influx-cli) + - [InfluxDB API](#influxdb-api) - [Other ways to write data to InfluxDB](#other-ways-to-write-data-to-influxdb) -## Requirements to write data +### What you'll need -To write data to InfluxDB, you must have an organization, bucket, authentication token, -and data formatted in line protocol. +#### The basics -### Organization +To write data into InfluxDB, you need an **organization**, a **bucket**, and an **authentication token**. +(All InfluxDB write interactions require an [authentication token](/v2.0/security/tokens/).) +If you've installed using the graphical UI, you should have been guided through creating all of these. -The organization in which to write data. -Use your organization name or ID. +#### Data -### Bucket +Of course, you'll also need data. +Use _line protocol_ format to write data into InfluxDB. +Each line represents a data point. +Each point requires a [*measurement*](/v2.0/reference/line-protocol/#measurement) +and [*field set*](/v2.0/reference/line-protocol/#field-set) and may also include +a [*tag set*](/v2.0/reference/line-protocol/#tag-set) and a [*timestamp*](/v2.0/reference/line-protocol/#timestamp). -The bucket in which to write data. -Use the bucket name or ID. -The bucket must belong to the specified organization. +Line protocol data looks like this: -### Precision +```sh +mem,host=host1 used_percent=23.43234543 1556892576842902000 +cpu,host=host1 usage_user=3.8234,usage_system=4.23874 1556892726597397000 +mem,host=host1 used_percent=21.83599203 1556892777007291000 +``` -The precision of timestamps provided in the line protocol. -Default timestamp precision is in nanoseconds. +Timestamps are essential in InfluxDB. +If a data point does not include a timestamp when it is received by the database, InfluxDB uses the current system time (UTC) of its host machine. -If the precision of the timestamps is anything other than nanoseconds (ns), +The default precision for timestamps is in nanoseconds. +If the precision of the timestamps is anything other than nanoseconds (`ns`), you must specify the precision in your write request. InfluxDB accepts the following precisions: @@ -51,36 +56,93 @@ InfluxDB accepts the following precisions: - `ms` - Milliseconds - `s` - Seconds -### Authentication token - -All InfluxDB write interactions require an [authentication token](/v2.0/security/tokens/). - -### Line protocol - -Use line protocol to write data points to InfluxDB. -Each line represents a data point. -Each point requires a [measurement](/v2.0/reference/line-protocol/#measurement) -and [field set](/v2.0/reference/line-protocol/#field-set) but can also include -a [tag set](/v2.0/reference/line-protocol/#tag-set) and a [timestamp](/v2.0/reference/line-protocol/#timestamp). - -{{% note %}} -_If a data point does not include a timestamp, InfluxDB uses the system time (UTC) -of its host machine when it receives the data point._ -{{% /note %}} - -##### Example line protocol - -```sh -mem,host=host1 used_percent=23.43234543 1556892576842902000 -cpu,host=host1 usage_user=3.8234,usage_system=4.23874 1556892726597397000 -mem,host=host1 used_percent=21.83599203 1556892777007291000 -``` - -_For details about line protocol, see the [Line protocol reference](/v2.0/reference/line-protocol) ._ +_For more details about line protocol, see the [Line protocol reference](/v2.0/reference/line-protocol)._ -## Write data using the InfluxDB v2 API +## Ways to write data into InfluxDB +To write data into InfluxDB, use one of the following methods: + +- [User Interface](#user-interface) +- [influx CLI](#influx-cli) +- [InfluxDB API](#influxdb-api) + +### User Interface + +To quickly start writing data, use the provided user interface. +By default the UI is at http://localhost:9999. +Launch `influxdb`, and navigate to the interface using a web browser. +Then follow the instructions below. + +1. Click **Load Your Data** in the navigation menu. +2. Select the **Buckets** tab. +3. Under the bucket you want to write data to, click **{{< icon "plus" >}} Add Data**. +4. Select from the following options: + + - [Configure Telegraf Agent](#configure-telegraf-agent) + - [Line Protocol](#line-protocol) + - [Scrape Metrics](#scrape-metrics) + +--- + +#### Configure Telegraf Agent + +To configure a Telegraf agent, see [Automatically create a Telegraf configuration](/v2.0/write-data/use-telegraf/auto-config/#create-a-telegraf-configuration). + +--- + +#### Line Protocol + +1. Select **Upload File** or **Enter Manually**. + - **Upload File:** + Select the time precision of your data. + Drag and drop the line protocol file into the UI or click to select the + file from your file manager. + - **Enter Manually:** + Select the time precision of your data. + Manually enter line protocol. +2. Click **Continue**. + A message indicates whether data is successfully written to InfluxDB. +3. To add more data or correct line protocol, click **Previous**. +4. Click **Finish**. + +--- + +#### Scrape Metrics + +To scrape metrics, see [Create a scraper](/v2.0/write-data/scrape-data/manage-scrapers/create-a-scraper/#create-a-scraper-in-the-influxdb-ui). + +{{% cloud-msg %}}{{< cloud-name >}} does not support scrapers. +{{% /cloud-msg %}} + +### influx CLI + +From the command line, use the [`influx write` command](/v2.0/reference/cli/influx/write/) to write data to InfluxDB. +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 the `-p`, `--precision` flag. | +| Authentication token | Set the `INFLUX_TOKEN` environment variable or use the `t`, `--token` flag. | +| Line protocol | Write a single line as a string or pass a file path prefixed with `@`. | + +To write a single data point, for example, run + +```sh +influx write -b bucketName -o orgName -p s 'myMeasurement,host=myHost testField="testData" 1556896326' +``` + +To write data in line protocol from a file, try + +``` +influx write -b bucketName -o orgName -p s @/path/to/line-protocol.txt +``` + +### InfluxDB API + +You can also write to InfluxDB using raw http requests. Use the InfluxDB API `/write` endpoint to write data to InfluxDB. Include the following in your request: @@ -92,90 +154,16 @@ Include the following in your request: | Authentication token | Use the `Authorization: Token` header. | | Line protocol | Pass as plain text in your request body. | -###### Example API write request +Below is an example API write request using `curl`: ```sh -curl "http://localhost:9999/api/v2/write?org=YOUR_ORG&bucket=YOUR_BUCKET&precision=s" \ +curl -XPOST "http://localhost:9999/api/v2/write?org=YOUR_ORG&bucket=YOUR_BUCKET&precision=s" \ --header "Authorization: Token YOURAUTHTOKEN" \ --data-raw "mem,host=host1 used_percent=23.43234543 1556896326" ``` +permalink -## Write data using the influx CLI - -Use the [`influx write` command](/v2.0/reference/cli/influx/write/) to write data to InfluxDB. -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 the `-p`, `--precision` flag. | -| Authentication token | Set the `INFLUX_TOKEN` environment variable or use the `t`, `--token` flag. | -| Line protocol | Write a single line as a string or pass a file path prefixed with `@`. | - - -##### Example influx write commands - -```sh -# Write a single data point -influx write -b bucketName -o orgName -p s 'myMeasurement,host=myHost testField="testData" 1556896326' - -# Write multiple data points -influx write -b bucketName -o orgName -p s 'myMeasurement,host=myHost testField="testData" 1556896326\nmyMeasurement2,host=myHost testField2="testData" 1556896327\nmyMeasurement3,host=myHost testField3="testData" 1556896328' - -# Write line protocol from a file -influx write -b bucketName -o orgName -p s @/path/to/line-protocol.txt - -To write multiple lines in one request, add the newline character `\n` to the end of each line. -``` - -## Write data in the InfluxDB UI - -1. Click **Load Data** in the left navigation menu. - - {{< nav-icon "load data" >}} - -2. Select **Buckets**. -3. Under the bucket you want to write data to, click **{{< icon "plus" >}} Add Data**. -4. Select from the following options: - - - [Configure Telegraf Agent](#configure-telegraf-agent) - - [Line Protocol](#line-protocol-1) - - [Scrape Metrics](#scrape-metrics) - - --- - - ### Configure Telegraf Agent - - To configure a Telegraf agent, see [Automatically create a Telegraf configuration](/v2.0/write-data/use-telegraf/auto-config/#create-a-telegraf-configuration). - - --- - - ### Line Protocol - - 1. Select **Upload File** or **Enter Manually**. - - **Upload File:** - Select the time precision of your data. - Drag and drop the line protocol file into the UI or click to select the - file from your file manager. - - **Enter Manually:** - Select the time precision of your data. - Manually enter line protocol. - 2. Click **Continue**. - A message indicates whether data is successfully written to InfluxDB. - 3. To add more data or correct line protocol, click **Previous**. - 4. Click **Finish**. - - --- - - ### Scrape Metrics - - To scrape metrics, see [Create a scraper](/v2.0/write-data/scrape-data/manage-scrapers/create-a-scraper/#create-a-scraper-in-the-influxdb-ui). - - {{% cloud-msg %}}{{< cloud-name >}} does not support scrapers. - {{% /cloud-msg %}} - -## Other ways to write data to InfluxDB +### Other ways to write data to InfluxDB {{< children >}} From f0dbd44a75ffdca5ff3af93dd136837a4cf8c377 Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Fri, 11 Oct 2019 11:19:22 -0700 Subject: [PATCH 2/3] Further revise "Write Data" guide --- content/v2.0/write-data/_index.md | 32 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/content/v2.0/write-data/_index.md b/content/v2.0/write-data/_index.md index 6b6fc3d30..7a29700c3 100644 --- a/content/v2.0/write-data/_index.md +++ b/content/v2.0/write-data/_index.md @@ -11,22 +11,22 @@ menu: v2.0/tags: [write, line protocol] --- +Collect and write time series data to InfluxDB using [line protocol](/v2.0/reference/line-protocol), +Telegraf, data scrapers, the InfluxDB v2 API, `influx` command line interface (CLI), +the InfluxDB user interface (UI), and client libraries. + - [What you'll need](#what-you-ll-need) - [Ways to write data into InfluxDB](#ways-to-write-data-into-influxdb) - [User Interface](#user-interface) - [influx CLI](#influx-cli) - [InfluxDB API](#influxdb-api) -- [Other ways to write data to InfluxDB](#other-ways-to-write-data-to-influxdb) +- [Others](#others) ### What you'll need -#### The basics - To write data into InfluxDB, you need an **organization**, a **bucket**, and an **authentication token**. (All InfluxDB write interactions require an [authentication token](/v2.0/security/tokens/).) -If you've installed using the graphical UI, you should have been guided through creating all of these. - -#### Data +The [InfluxDB setup process](/v2.0/get-started/#set-up-influxdb) creates each of these. Of course, you'll also need data. Use _line protocol_ format to write data into InfluxDB. @@ -56,8 +56,7 @@ InfluxDB accepts the following precisions: - `ms` - Milliseconds - `s` - Seconds -_For more details about line protocol, see the [Line protocol reference](/v2.0/reference/line-protocol)._ - +_For more details about line protocol, see the [Line protocol reference](/v2.0/reference/line-protocol) and [Best practices for writing data](/v2.0/write-data/best-practices/)._ ## Ways to write data into InfluxDB @@ -70,12 +69,9 @@ To write data into InfluxDB, use one of the following methods: ### User Interface To quickly start writing data, use the provided user interface. -By default the UI is at http://localhost:9999. -Launch `influxdb`, and navigate to the interface using a web browser. -Then follow the instructions below. -1. Click **Load Your Data** in the navigation menu. -2. Select the **Buckets** tab. +1. Click **Load Data** in the navigation menu. +2. Select **Buckets**. 3. Under the bucket you want to write data to, click **{{< icon "plus" >}} Add Data**. 4. Select from the following options: @@ -128,6 +124,8 @@ Include the following in your command: | Authentication token | Set the `INFLUX_TOKEN` environment variable or use the `t`, `--token` flag. | | Line protocol | Write a single line as a string or pass a file path prefixed with `@`. | +##### Example influx write commands + To write a single data point, for example, run ```sh @@ -142,8 +140,7 @@ influx write -b bucketName -o orgName -p s @/path/to/line-protocol.txt ### InfluxDB API -You can also write to InfluxDB using raw http requests. -Use the InfluxDB API `/write` endpoint to write data to InfluxDB. +Write data to InfluxDB using an HTTP request to the InfluxDB API write endpoint. Include the following in your request: | Requirement | Include by | @@ -154,6 +151,8 @@ Include the following in your request: | Authentication token | Use the `Authorization: Token` header. | | Line protocol | Pass as plain text in your request body. | +##### Example API write request + Below is an example API write request using `curl`: ```sh @@ -161,9 +160,8 @@ curl -XPOST "http://localhost:9999/api/v2/write?org=YOUR_ORG&bucket=YOUR_BUCKET& --header "Authorization: Token YOURAUTHTOKEN" \ --data-raw "mem,host=host1 used_percent=23.43234543 1556896326" ``` -permalink -### Other ways to write data to InfluxDB +### Others {{< children >}} From 46fe5225b1a1382412a53f50e31187fd5942e6a5 Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Fri, 11 Oct 2019 12:55:51 -0700 Subject: [PATCH 3/3] Edit "Write Data" guide --- content/v2.0/write-data/_index.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/content/v2.0/write-data/_index.md b/content/v2.0/write-data/_index.md index 7a29700c3..b884ab9c0 100644 --- a/content/v2.0/write-data/_index.md +++ b/content/v2.0/write-data/_index.md @@ -24,11 +24,14 @@ the InfluxDB user interface (UI), and client libraries. ### What you'll need -To write data into InfluxDB, you need an **organization**, a **bucket**, and an **authentication token**. -(All InfluxDB write interactions require an [authentication token](/v2.0/security/tokens/).) +To write data into InfluxDB, you need the following: + +- an **organization** +- a **bucket**; and +- an [**authentication token**](/v2.0/security/tokens/). + The [InfluxDB setup process](/v2.0/get-started/#set-up-influxdb) creates each of these. -Of course, you'll also need data. Use _line protocol_ format to write data into InfluxDB. Each line represents a data point. Each point requires a [*measurement*](/v2.0/reference/line-protocol/#measurement) @@ -70,10 +73,15 @@ To write data into InfluxDB, use one of the following methods: To quickly start writing data, use the provided user interface. -1. Click **Load Data** in the navigation menu. -2. Select **Buckets**. -3. Under the bucket you want to write data to, click **{{< icon "plus" >}} Add Data**. -4. Select from the following options: +1. Do one of the following: + - _InfluxDB 2.0 OSS users_: + In your terminal, run `influxd` and then in your browser, go to the location where you're hosting the UI (by default, localhost:9999). + - _InfluxDB 2.0 Cloud users_: + In your browser, go to https://cloud2.influxdata.com/. +2. Click **Load Data** in the navigation menu on the left. +3. Select **Buckets**. +4. Under the bucket you want to write data to, click **{{< icon "plus" >}} Add Data**. +5. Select from the following options: - [Configure Telegraf Agent](#configure-telegraf-agent) - [Line Protocol](#line-protocol) @@ -140,7 +148,7 @@ influx write -b bucketName -o orgName -p s @/path/to/line-protocol.txt ### InfluxDB API -Write data to InfluxDB using an HTTP request to the InfluxDB API write endpoint. +Write data to InfluxDB using an HTTP request to the InfluxDB API `/write` endpoint. Include the following in your request: | Requirement | Include by |