influxdata / docs-v2 Goto Github PK

InfluxData Documentation that covers InfluxDB Cloud, InfluxDB OSS 2.x, InfluxDB OSS 1.x, InfluxDB Enterprise, Telegraf, Chronograf, Kapacitor, and Flux.

Home Page: https://docs.influxdata.com

License: MIT License

HTML 29.94% JavaScript 21.24% Shell 8.21% Ruby 0.62% Handlebars 0.36% SCSS 39.00% Dockerfile 0.63%

docs-v2's Introduction

InfluxDB 2.0 Documentation

This repository contains the InfluxDB 2.x documentation published at docs.influxdata.com.

Contributing

We welcome and encourage community contributions. For information about contributing to the InfluxData documentation, see Contribution guidelines.

Reporting a Vulnerability

InfluxData takes security and our users' trust very seriously. If you believe you have found a security issue in any of our open source projects, please responsibly disclose it by contacting [email protected]. More details about security vulnerability reporting, including our GPG key, can be found at https://www.influxdata.com/how-to-report-security-vulnerabilities/.

Running the docs locally

Clone this repository to your local machine.
Install NodeJS, Yarn, Hugo, & Asset Pipeline Tools

The InfluxData documentation uses Hugo, a static site generator built in Go. The site uses Hugo's asset pipeline, which requires the extended version of Hugo along with NodeJS tools like PostCSS, to build and process stylesheets and JavaScript.

To install the required dependencies and build the assets, do the following:
1. Install NodeJS
2. Install Yarn
3. In your terminal, from the docs-v2 directory, install the dependencies:
```
cd docs-v2
yarn install
```
  Note: The most recent version of Hugo tested with this documentation is 0.123.8.
To generate the API docs, see api-docs/README.md.
Start the Hugo server

Hugo provides a local development server that generates the HTML pages, builds the static assets, and serves them at localhost:1313.

In your terminal, start the Hugo server:
```
npx hugo server
```
View the docs at localhost:1313.

Alternative: Use docker compose

Clone this repository to your local machine. See how to clone a repository.
Follow the instructions to install Docker Desktop and Docker Compose to your local machine.
Use Docker Compose to start the Hugo server in development mode--for example, enter the following command in your terminal:
```
docker compose up local-dev
```
View the docs at localhost:1313.

docs-v2's People

Stargazers

Watchers

Forkers

hoorayimhelping turingzhu rawkode vijetah huiyuanjian dspeichert sgnl oren-nonamesecurity picaosgeo gotjoshua bonitoo-io influxdata-cn nguyenmp hraftery vlastahajek sranka samueltoh sbollain skillz4killz jsteenb2 wtkwsk testudy vincentyuan-hub ajax001001 mustafa-erduran eraac jianyuecc nocibambi mprevide nemecsek stefanxfy caleb15 evanalexandre iv587 devopstoday11 qxslew rhajek ch3fch3f harrisondnash strongwind0 stoneyunzhao janpieper vdelany gmale blueskyfr oori w33bion haxtibal laashub-soa coderxloong bankhappy8 liumengyang xiakaibi seantbooker hehexiaohei bigjaked vutting4221 yu-mr1019 kimsehwan96 pbdeuchler roelvliegen elwin1234 excaptor dhoard paulschulz lanceybp icloudsong stakach git001 awfeequdng mia-joy-liang matthewstidham iammathh vzamko seyyedkhandon sebastianthorn azadbabu sparris79 dahlinpl sanisoft2016 eric-arellano theodiefenthal deepaksreedharan-abb aberkecz ericvolp12 navifra-kerry blazej24 xxxu clwluvw duxzs nobuhito neelayu smzgit aradnaev phillipleblanc sixther-dc maksimpuzyrkov slawr nallwhy fredericosilva

docs-v2's Issues

Document import/export tasks

Create a 404 page

Telegraf Config -- add instructions for adding InfluxDB v2 output plugin

We should write some instructions for existing users of Telegraf.

The instructions should highlight how to add the appropriate configuration settings for the InfluxDB v2 output plugin to an EXISTING Telegraf configuration file.

Add cloud and feedback icons

Add a cloud and feedback left nav icons. Possibly in-line icons for each as well.

Document InfluxDB 2 configuration and defaults

Doc explaining how to configure InfluxDB 2.
Reference doc with config defaults.

Update Histograms guide with info about the histogram visualization

InfluxDB's histogram visualization type doesn't display data produced by Flux's current histogram() function; it creates an "ad-hoc" histogram based off the structure of the returned data. We need to document how data should be structured to provide a useful data visualization and give good Flux examples of transforming data into that structure.

Add switch organizations menu to home navigation

Org management now lives in the admin section of the left nav--need to update all CRUD org docs

Ability to edit token's description

Alpha Scope - Jan 23rd!

Docs To-Do's

Full Alpha Scope

Setup UI
Setup via CLI
Write data from Telegraf -- need to describe what is/is not supported for Telegraf config
Query builder UI & Dashboards
Org, bucket, token CRUD UI
Org, bucket, token CRUD CLI
Task CRUD via UI
Task CRUD via CLI
Ingest metrics from OSS process (+ UI for what org/bucket it goes to)
Metrics endpoint for InfluxDB v2.0
Flux namespaces & standard library
Flux nil
Flux fill
Flux friendly parser errors
Flux REPL
Docs
Phone home usage stats
Nightly builds (deb, rpm, docker)
Weekly builds with changelog -- docs needs to determine taxonomy for changelog now that we are in single node binary
Move of Platform to InfluxDB -- target Jan 8th
Docs: Define expectations of data model and consistency approach

Add rel=canonical to old versions

To avoid SEO penalties for duplicate content, we need to add the rel="canonical" meta tag to old versions that point to the newest version of the current page. Something like the following in the <head>:

{{ $currentVersion := (index (findRE "[^/]+.*?" .RelPermalink) 0) .RelPermalink }}
{{ $latestVersion := $.Site.Data.versions.latest_version }}
{{ $latestVersionURL := replaceRE "[^/]+.*?[0]" $latestVersion .RelPermalink }}
{{ if not (eq $currentVersion $latestVersion) }}
  <link rel=”canonical” href=”{{ $latestVersionURL }}” />
{{ end }}

Document how to write data to InfluxDB 2.0

We need to document how to write data to InfluxDB. Currently we only offer docs for using Telegraf or scrapers to get data in. Things we need include:

Document renaming orgs, buckets, etc.

A good example to pattern this doc after would be Github's renaming an org doc:
https://help.github.com/en/articles/renaming-an-organization

noindex tag on old versions

Update changelog for alpha 8

Create custom aggregate functions guide

This guide should cover creating custom aggregate functions using the reduce() function.

Create key terms / glossary doc

URL configuration should give more cloud guidance

https://v2.docs.influxdata.com/v2.0/collect-data/use-telegraf/manual-config/

Making cloud urls explicit, where to look for the cloud URL in a user's cloud setup, and perhaps a cloud example here would ease the user into configuring telegraf to get data to cloud.

Create annotated CSV format reference doc

The content can be pulled from this section of the Flux spec:

https://github.com/influxdata/flux/blob/master/docs/SPEC.md#csv

Document new template variables

~~Template variables~~ -> Variables

Predefined variables:

v.timeRangeStart
v.timeRangeEnd
v.windowPeriod

Custom variables: In alpha-7, custom variable values can only be populated using a query. "Staticly-defined" variables are coming.

We also need to document how to import/export variables.

Dashboard variable names should be unique

The UI now validates that variable names are unique. We mention in the docs that variables must be unique within the same organization.

Add Google Analytics

Document how to use Vault as a secret store with InfluxDB 2

Only include the most recent version in sitemap

Enrich the Install instructions

no redirect to the downloads page
create specific instructions per platform (Darwin, Docker, Linux, tar ball)...review 1.x install instructions by platform/OS for inspiration
review collapsing into a single page rather than separate pages for install and setup
Add the call to action re: feedback on the alpha/beta
here: https://community.influxdata.com/c/influxdb2

2.0 HTTP API docs

We can use the swagger.yml to generate the API docs.

https://github.com/influxdata/influxdb/blob/master/http/swagger.yml

Document using tokens with CLI after UI initialization

Whenever a 2.0 database is initialized through the UI, the root token DOES NOT get stored on the user's machine. influx setup will store the generated token in the user's home directory and the user won't have to pass a token with any commands. If somebody initializes their DB through the UI and wants to use the CLI, they need to pass their token using one of the following methods:

Use the -t --token flag when running influx commands to pass the token.
Set the INFLUX_TOKEN environment variable.
Store their token in ~/.influxdbv2/credentials. Tokens can be retrieved from the UI.

Remove protos

https://github.com/influxdata/idpe/pull/3044
influxdata/influxdb#13061

We are removing the protos references from influxdb. Any references related to protos fs
for example

--protos-path | Path to protos on the filesystem (default ~/.influxdbv2/protos)

Docs: Generate Telegraf docs from in-tree plugin markdown files

Overview

Turn some Telegraf project readmes into fulll pages on pages in docs.influxdata.com. Pull directly from GitHub readme so when readme is updated so does the docs page.

All Markdown documents in the Telegraf repo are now fully linted and linted before every check-in. Every file was gone through and standardized on a set of header levels and patterns.

Proposal

GitHub pages to include:

All plugins
https://github.com/influxdata/telegraf/blob/master/docs/CONFIGURATION.md

Use case

A better experience for users via:
- some may get distracted when they go from docs to GitHub, end up giving up
- create a cohesive InfluxData experience
- up to date docs
Less maintenance burden on docs team
Gain analytics to see who's viewing the plugin readmes, which ones are giving users more trouble

Next Steps

Docs team to investigate how this could be done
Docs team to let Telegraf team know if Markdown files are meeting their standard or if templates need updates

Add labels to variables

Update UI images for alpha-8

Document where to get your org ID

In the UI, you can get it from the URL:

# Pattern
http://localhost:9999/orgs/<org-id>

# Example
http://localhost:9999/orgs/03a2bbf46249a000

From the CLI, you can see it in the output of:

influx org find

API requests need an org parameter

https://v2.docs.influxdata.com/v2.0/query-data/execute-queries/#influxdb-api

The API request examples need to include an org parameter.

Document new influxd subcommands

generate
inspect

Add favicon

Fix sorting in children shortcode

Update org management docs

Org management now lives in the admin section of the left nav.

Public 2.0 docs suggest to open issues in this (private) repo

We point people toward the new documentation in Alpha, and within these docs there are links suggesting people open issues, but the linked repo is this one -- private, so users will see a 404.

Maybe a better workflow would be for that link to point toward the existing public docs repo. There's no "v2" label now, but if there was, you could change the link to automatically label it with v2 for easier sorting/triage/differentiation between existing and new (e.g., https://github.com/influxdata/docs.influxdata.com/issues/new?labels=v2)

Fix font rendering

Document import/export dashboards

Alpha - Flux

Inputs

buckets
from
from_csv

Output

to_http
to_kafka
to_influx

Transformations

count
covariance
cumulative_sum
derivative
difference
distinct
filter
first
group
histogram [?]
increase
integral
join
key_values
keys
last
limit
map
max
mean
min
percentile
pivot
range
sample
schema_functions [?]
set
shift
skew
sort
spread
stddev
sum
system_time
top bottom
union
unique
window
yield

Column Types

bool
uint
int
float
time
nil

Flux value Types

bool
uint
int
float
duration
string
regex
array
object
function

Code organization

packages, namespaces, imports

Options

now
task

Constants and Built-ins

Days of week
Months of year

Document expected date formats for Flux

Update manage tokens docs

Update fromCSV function

The current fromCSV function is incorrect. It is now a package that must be imported. Pull from a csv data source with:

import "csv"
csv.from(...)

Create dashboard from a template

Full Disclosure: OSS Telemetry

We need to document that we have an opt-out feature which sends telemetry to InfluxData. We need to describe the details of what are capturing and why similar to the following examples:

https://www.elastic.co/guide/en/cloud-enterprise/current/ece-phone-home.html
https://caddyserver.com/docs/telemetry

This page should live at telemetry.influxdata.com ---

However, we need a pointer to this page from:
the InfluxDB 2.0 OSS repo
and
configuration of this.... essentially what you need to opt-out of this feature.

@goller is the key contact for the details.

Update manage labels doc

Document InfluxDB tracing

There are two options for tracing:

log
jaeger

Jaeger

If the tracing type flag == jaeger, then we use the Jaeger library to configure a Jaeger tracing destination.
https://sourcegraph.internal/github.com/influxdata/influxdb/-/blob/cmd/influxd/launcher/launcher.go#L360-374

Jaeger has great docs for this.
https://www.jaegertracing.io/docs/1.11/client-libraries/
https://www.jaegertracing.io/docs/1.11/client-features/

In the second Jaeger link, you’ll find a section “Tracer configuration via environment variables”. At a minimum, the InfluxDB OSS 2.x user will need to set these env vars:
JAEGER_AGENT_HOST - Jaeger agent host name or IP address
JAEGER_SERVICE_NAME - “service name” added to each trace

format for the content (output from Hugo?)
publishing process and frequency (limits?, controls?)

We will need to work with @gunnaraasen very closely on this effort.