diff --git a/content/v2.0/write-data/_index.md b/content/v2.0/write-data/_index.md index 6f85401a1..b884ab9c0 100644 --- a/content/v2.0/write-data/_index.md +++ b/content/v2.0/write-data/_index.md @@ -15,34 +15,42 @@ Collect and write time series data to InfluxDB using [line protocol](/v2.0/refer 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) -- [Other ways to write data to InfluxDB](#other-ways-to-write-data-to-influxdb) +- [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) +- [Others](#others) -## 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. +To write data into InfluxDB, you need the following: -### Organization +- an **organization** +- a **bucket**; and +- an [**authentication token**](/v2.0/security/tokens/). -The organization in which to write data. -Use your organization name or ID. +The [InfluxDB setup process](/v2.0/get-started/#set-up-influxdb) creates each of these. -### Bucket +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,58 +59,69 @@ InfluxDB accepts the following precisions: - `ms` - Milliseconds - `s` - Seconds -### Authentication token +_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/)._ -All InfluxDB write interactions require an [authentication token](/v2.0/security/tokens/). +## Ways to write data into InfluxDB -### Line protocol +To write data into InfluxDB, use one of the following methods: -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). +- [User Interface](#user-interface) +- [influx CLI](#influx-cli) +- [InfluxDB API](#influxdb-api) -{{% 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 %}} +### User Interface -##### Example line protocol +To quickly start writing data, use the provided user interface. -```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 -``` +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: -_For details about line protocol, see the [Line protocol reference](/v2.0/reference/line-protocol) ._ - + - [Configure Telegraf Agent](#configure-telegraf-agent) + - [Line Protocol](#line-protocol) + - [Scrape Metrics](#scrape-metrics) -## Write data using the InfluxDB v2 API +--- -Use the InfluxDB API `/write` endpoint to write data to InfluxDB. -Include the following in your request: +#### Configure Telegraf Agent -| Requirement | Include by | -|:----------- |:---------- | -| Organization | Use the `org` query parameter in your request URL. | -| Bucket | Use the `bucket` query parameter in your request URL. | -| Precision | Use the `precision` query parameter in your request URL. | -| Authentication token | Use the `Authorization: Token` header. | -| Line protocol | Pass as plain text in your request body. | +To configure a Telegraf agent, see [Automatically create a Telegraf configuration](/v2.0/write-data/use-telegraf/auto-config/#create-a-telegraf-configuration). -###### Example API write request +--- -```sh -curl "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" -``` +#### Line Protocol -## Write data using the influx CLI +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**. -Use the [`influx write` command](/v2.0/reference/cli/influx/write/) to write data to InfluxDB. +--- + +#### 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 | @@ -113,69 +132,44 @@ 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 -# 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 +To write data in line protocol from a file, try -1. Click **Load Data** in the left navigation menu. +``` +influx write -b bucketName -o orgName -p s @/path/to/line-protocol.txt +``` - {{< nav-icon "load data" >}} +### InfluxDB API -2. Select **Buckets**. -3. Under the bucket you want to write data to, click **{{< icon "plus" >}} Add Data**. -4. Select from the following options: +Write data to InfluxDB using an HTTP request to the InfluxDB API `/write` endpoint. +Include the following in your request: - - [Configure Telegraf Agent](#configure-telegraf-agent) - - [Line Protocol](#line-protocol-1) - - [Scrape Metrics](#scrape-metrics) +| Requirement | Include by | +|:----------- |:---------- | +| Organization | Use the `org` query parameter in your request URL. | +| Bucket | Use the `bucket` query parameter in your request URL. | +| Precision | Use the `precision` query parameter in your request URL. | +| Authentication token | Use the `Authorization: Token` header. | +| Line protocol | Pass as plain text in your request body. | - --- +##### Example API write request - ### 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). +Below is an example API write request using `curl`: - --- +```sh +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" +``` - ### 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 +### Others {{< children >}}