Enhancements to Line Protocol documentation (v2 doc)

[alsargent]

I spent some time with a customer today struggling to write line protocol using curl. Some of his struggles seem to have been caused by gaps in our documentation of line protocol. Here are suggestions to fill those gaps.

Maybe these tips exist in other pages; if so, please link to them.

#1: curl Examples

Our v1 doc page had examples using curl, showing both what the user submits and the expected return value. Our v2 docs doesn't have any similar examples using curl. We should provide a number of working examples with curl.

These examples should work for both localhost and one example of suing a cloud 2 URL. Provide a link to our cloud 2 URLs page.

The curl example in https://v2.docs.influxdata.com/v2.0/write-data/ didn't seem to work for the customer, since it contained a Unix timestamp at the end:

curl -XPOST "YOUR-INFLUXDB-CLOUD-URL/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"

#2: curl options

We should explain which curl options are best to use. Does curl -XPOST work? How about curl --request POST? Asking because the customer is working in a constrained IoT environment has is limited in what kinds of curl options he can use.

Not looking for a complete guide to curl, just a couple of options that one should use.

#3: Unix time

Explain the concept of Unix time (seconds since 1970) -- as is done in the v1 doc -- and link to a google search to find Unix time-to-human time conversion.

#4: gzip compression

gzip compression can increase performance by ~8x according to some recent benchmarks. v1 doc explained how to do gzip compression. v2 doc should do the same.

#5: Multiple points

v1 doc provided examples of how to write multiple points. v2 doc should do the same.

#6: Writing from a file

v1 doc gave an example of writing line protocol from a file. v2 doc should do the same.

#7: Quick summary of REST and error codes

v1 doc explained rest and error codes. v2 doc should do the same.

#8: Next steps

The v1 doc concluded with next steps that the reader could take. v2 docs should also provide next steps.

Relevant URLs

v1 line protocol documenation:
https://docs.influxdata.com/influxdb/v1.7/guides/writing_data/

v2 line protocol documentation:
https://v2.docs.influxdata.com/v2.0/reference/syntax/line-protocol/

v2 writing data doc:
https://v2.docs.influxdata.com/v2.0/write-data/

[sanderson]

In 2.0, we've separated reference style content from task-based content. The v2 line protocol doc is a reference doc that outlines the structure and syntax of line protocol. The Write data doc is a task-based doc that walks through multiple methods for writing data to InfluxDB. With that context, I propose the following changes:

1. curl Examples

   • Add a very apparent link from the Line Protocol doc to the Write data doc
   • Add a version of the curl API call using an InfluxDB Cloud URL
   • Include a link to the Cloud URLs doc
   • Add a link in the Write data doc that links to the Timestamp section of the line protocol doc that states timestamps are optional be we recommend including them.

2. curl options

   • Clarify that the /write endpoint only requires the POST request-method (curl -X and curl --request are the same)

3. Unix time

   • Add description of what a Unix timestamp is (either in the Write data doc or in the Glossary with a link from the Write data doc)

4. gzip compression

   • Add note about using gzip compression to the API example in the Write data doc.

5. Multiple points

   • Update the API example in the Write data doc to show writing multiple points.

6. Writing from a file

   • The Write data doc already shows how to write from a file. Note: This command will change with the next beta.
   • Give the "write from a file" example a header to anchor to.

7. Quick summary of REST and error codes

   • This is covered in the API doc. There's no need to re-document them here too.
   • Add link to the /write API swagger where they can view response codes: https://v2.docs.influxdata.com/v2.0/api/#operation/PostWrite

8. Next steps

   • I'm not seeing a "next steps" section in the v1 docs. Do you have a link?
   • Update the "Others" section title to "Other ways to write data to InfluxDB"
   • Add Next steps section at the end of the Write data doc (after the "Others" section).

[alsargent]

Ok, let's give that a shot and see how it goes. Thanks for the detailed list.