Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #513 from influxdata/revise-write-data 

Revise "Write Data" guide
pull/523/head
pierwill 2019-10-15 11:49:32 -07:00 committed by GitHub
parent 08c9dc63d3 46fe5225b1
commit bd460647b5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 100 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

206
content/v2.0/write-data/_index.md
View File

@ -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), Telegraf, data scrapers, the InfluxDB v2 API, `influx` command line interface (CLI),
the InfluxDB user interface (UI), and client libraries. the InfluxDB user interface (UI), and client libraries.
- [Requirements to write data](#requirements-to-write-data) - [What you'll need](#what-you-ll-need)
- [InfluxDB v2 API](#write-data-using-the-influxdb-v2-api) - [Ways to write data into InfluxDB](#ways-to-write-data-into-influxdb)
- [influx CLI](#write-data-using-the-influx-cli) - [User Interface](#user-interface)
- [InfluxDB UI](#write-data-in-the-influxdb-ui) - [influx CLI](#influx-cli)
- [Other ways to write data to InfluxDB](#other-ways-to-write-data-to-influxdb) - [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, To write data into InfluxDB, you need the following:
and data formatted in line protocol.
### Organization - an **organization**
- a **bucket**; and
- an [**authentication token**](/v2.0/security/tokens/).
The organization in which to write data. The [InfluxDB setup process](/v2.0/get-started/#set-up-influxdb) creates each of these.
Use your organization name or ID.
### 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. Line protocol data looks like this:
Use the bucket name or ID.
The bucket must belong to the specified organization.
### 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. Timestamps are essential in InfluxDB.
Default timestamp precision is in nanoseconds. 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. you must specify the precision in your write request.
InfluxDB accepts the following precisions: InfluxDB accepts the following precisions:
@ -51,58 +59,69 @@ InfluxDB accepts the following precisions:
- `ms` - Milliseconds - `ms` - Milliseconds
- `s` - Seconds - `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. - [User Interface](#user-interface)
Each line represents a data point. - [influx CLI](#influx-cli)
Each point requires a [measurement](/v2.0/reference/line-protocol/#measurement) - [InfluxDB API](#influxdb-api)
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 %}} ### User Interface
_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 To quickly start writing data, use the provided user interface.
```sh 1. Do one of the following:
mem,host=host1 used_percent=23.43234543 1556892576842902000 - _InfluxDB 2.0 OSS users_:
cpu,host=host1 usage_user=3.8234,usage_system=4.23874 1556892726597397000 In your terminal, run `influxd` and then in your browser, go to the location where you're hosting the UI (by default, localhost:9999).
mem,host=host1 used_percent=21.83599203 1556892777007291000 - _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)
<!-- Link to line protocol best practices --> - [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. #### Configure Telegraf Agent
Include the following in your request:
| Requirement | Include by | To configure a Telegraf agent, see [Automatically create a Telegraf configuration](/v2.0/write-data/use-telegraf/auto-config/#create-a-telegraf-configuration).
|:----------- |:---------- |
| 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 ---
```sh #### Line Protocol
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"
```
## 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: Include the following in your command:
| Requirement | Include by | | 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. | | 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 `@`. | | Line protocol | Write a single line as a string or pass a file path prefixed with `@`. |
##### Example influx write commands ##### Example influx write commands
To write a single data point, for example, run
```sh ```sh
# Write a single data point
influx write -b bucketName -o orgName -p s 'myMeasurement,host=myHost testField="testData" 1556896326' 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**. Write data to InfluxDB using an HTTP request to the InfluxDB API `/write` endpoint.
3. Under the bucket you want to write data to, click **{{< icon "plus" >}} Add Data**. Include the following in your request:
4. Select from the following options:
- [Configure Telegraf Agent](#configure-telegraf-agent) | Requirement | Include by |
- [Line Protocol](#line-protocol-1) |:----------- |:---------- |
- [Scrape Metrics](#scrape-metrics) | 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 Below is an example API write request using `curl`:
To configure a Telegraf agent, see [Automatically create a Telegraf configuration](/v2.0/write-data/use-telegraf/auto-config/#create-a-telegraf-configuration).
--- ```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 ### Others
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
{{< children >}} {{< children >}}