github.com/influxdata/influxdb/v2@v2.7.6/README.md (about) 1 # InfluxDB 2 <div align="center"> 3 <img src="assets/influxdb-logo.png" width="600" alt="InfluxDB Logo"> 4 </div> 5 6 <p align="center"> 7 <a href="https://circleci.com/gh/influxdata/influxdb"> 8 <img alt="CircleCI" src="https://circleci.com/gh/influxdata/influxdb.svg?style=svg" /> 9 </a> 10 11 <a href="https://www.influxdata.com/slack"> 12 <img alt="Slack Status" src="https://img.shields.io/badge/slack-join_chat-white.svg?logo=slack&style=social" /> 13 </a> 14 15 <a href="https://docs.influxdata.com/influxdb/v2.4/install/?t=Docker"> 16 <img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/_/influxdb" /> 17 </a> 18 19 <a href="https://github.com/influxdata/influxdb/blob/master/LICENSE"> 20 <img alt="Docker Pulls" src="https://img.shields.io/github/license/influxdata/influxdb" /> 21 </a> 22 </p> 23 <h3 align="center"> 24 <b><a href="https://www.influxdata.com/">Website</a></b> 25 • 26 <a href="https://docs.influxdata.com/">Documentation</a> 27 • 28 <a href="https://university.influxdata.com/">InfluxDB University</a> 29 • 30 <a href="https://www.influxdata.com/blog/">Blog</a> 31 </h3> 32 33 --- 34 35 InfluxDB is an open source time series platform. This includes APIs for storing and querying data, processing it in the background for ETL or monitoring and alerting purposes, user dashboards, and visualizing and exploring the data and more. The master branch on this repo now represents the latest InfluxDB, which now includes functionality for Kapacitor (background processing) and Chronograf (the UI) all in a single binary. 36 37 The list of InfluxDB Client Libraries that are compatible with the latest version can be found in [our documentation](https://docs.influxdata.com/influxdb/latest/tools/client-libraries/). 38 39 If you are looking for the 1.x line of releases, there are branches for each minor version as well as a `master-1.x` branch that will contain the code for the next 1.x release. The master-1.x [working branch is here](https://github.com/influxdata/influxdb/tree/master-1.x). The [InfluxDB 1.x Go Client can be found here](https://github.com/influxdata/influxdb1-client). 40 41 | Try **InfluxDB Cloud** for free and get started fast with no local setup required. Click [**here**](https://cloud2.influxdata.com/signup) to start building your application on InfluxDB Cloud. | 42 |:------| 43 44 ## Install 45 46 We have nightly and versioned Docker images, Debian packages, RPM packages, and tarballs of InfluxDB available at the [InfluxData downloads page](https://portal.influxdata.com/downloads/). We also provide the `influx` command line interface (CLI) client as a separate binary available at the same location. 47 48 If you are interested in building from source, see the [building from source](CONTRIBUTING.md#building-from-source) guide for contributors. 49 50 <a href="https://university.influxdata.com/catalog/"> 51 <img src="assets/influxdbU-banner.png" width="600"/> 52 </a> 53 54 ## Get Started 55 56 For a complete getting started guide, please see our full [online documentation site](https://docs.influxdata.com/influxdb/latest/). 57 58 To write and query data or use the API in any way, you'll need to first create a user, credentials, organization and bucket. 59 Everything in InfluxDB is organized under a concept of an organization. The API is designed to be multi-tenant. 60 Buckets represent where you store time series data. 61 They're synonymous with what was previously in InfluxDB 1.x a database and retention policy. 62 63 The simplest way to get set up is to point your browser to [http://localhost:8086](http://localhost:8086) and go through the prompts. 64 65 You can also get set up from the CLI using the command `influx setup`: 66 67 68 ```bash 69 $ bin/$(uname -s | tr '[:upper:]' '[:lower:]')/influx setup 70 Welcome to InfluxDB 2.0! 71 Please type your primary username: marty 72 73 Please type your password: 74 75 Please type your password again: 76 77 Please type your primary organization name.: InfluxData 78 79 Please type your primary bucket name.: telegraf 80 81 Please type your retention period in hours. 82 Or press ENTER for infinite.: 72 83 84 85 You have entered: 86 Username: marty 87 Organization: InfluxData 88 Bucket: telegraf 89 Retention Period: 72 hrs 90 Confirm? (y/n): y 91 92 UserID Username Organization Bucket 93 033a3f2c5ccaa000 marty InfluxData Telegraf 94 Your token has been stored in /Users/marty/.influxdbv2/credentials 95 ``` 96 97 You can run this command non-interactively using the `-f, --force` flag if you are automating the setup. 98 Some added flags can help: 99 ```bash 100 $ bin/$(uname -s | tr '[:upper:]' '[:lower:]')/influx setup \ 101 --username marty \ 102 --password F1uxKapacit0r85 \ 103 --org InfluxData \ 104 --bucket telegraf \ 105 --retention 168 \ 106 --token where-were-going-we-dont-need-roads \ 107 --force 108 ``` 109 110 Once setup is complete, a configuration profile is created to allow you to interact with your local InfluxDB without passing in credentials each time. You can list and manage those profiles using the `influx config` command. 111 ```bash 112 $ bin/$(uname -s | tr '[:upper:]' '[:lower:]')/influx config 113 Active Name URL Org 114 * default http://localhost:8086 InfluxData 115 ``` 116 117 ## Write Data 118 Write to measurement `m`, with tag `v=2`, in bucket `telegraf`, which belongs to organization `InfluxData`: 119 120 ```bash 121 $ bin/$(uname -s | tr '[:upper:]' '[:lower:]')/influx write --bucket telegraf --precision s "m v=2 $(date +%s)" 122 ``` 123 124 Since you have a default profile set up, you can omit the Organization and Token from the command. 125 126 Write the same point using `curl`: 127 128 ```bash 129 curl --header "Authorization: Token $(bin/$(uname -s | tr '[:upper:]' '[:lower:]')/influx auth list --json | jq -r '.[0].token')" \ 130 --data-raw "m v=2 $(date +%s)" \ 131 "http://localhost:8086/api/v2/write?org=InfluxData&bucket=telegraf&precision=s" 132 ``` 133 134 Read that back with a simple Flux query: 135 136 ```bash 137 $ bin/$(uname -s | tr '[:upper:]' '[:lower:]')/influx query 'from(bucket:"telegraf") |> range(start:-1h)' 138 Result: _result 139 Table: keys: [_start, _stop, _field, _measurement] 140 _start:time _stop:time _field:string _measurement:string _time:time _value:float 141 ------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- 142 2019-12-30T22:19:39.043918000Z 2019-12-30T23:19:39.043918000Z v m 2019-12-30T23:17:02.000000000Z 2 143 ``` 144 145 Use the `-r, --raw` option to return the raw flux response from the query. This is useful for moving data from one instance to another as the `influx write` command can accept the Flux response using the `--format csv` option. 146 147 ## Script with Flux 148 149 Flux (previously named IFQL) is an open source functional data scripting language designed for querying, analyzing, and acting on data. Flux supports multiple data source types, including: 150 151 - Time series databases (such as InfluxDB) 152 - Relational SQL databases (such as MySQL and PostgreSQL) 153 - CSV 154 155 The source for Flux is [available on GitHub](https://github.com/influxdata/flux). 156 To learn more about Flux, see the latest [InfluxData Flux documentation](https://docs.influxdata.com/flux/) and [CTO Paul Dix's presentation](https://speakerdeck.com/pauldix/flux-number-fluxlang-a-new-time-series-data-scripting-language). 157 158 ## Contribute to the Project 159 160 InfluxDB is an [MIT licensed](LICENSE) open source project and we love our community. The fastest way to get something fixed is to open a PR. Check out our [contributing](CONTRIBUTING.md) guide if you're interested in helping out. Also, join us on our [Community Slack Workspace](https://influxdata.com/slack) if you have questions or comments for our engineering teams. 161 162 ## CI and Static Analysis 163 164 ### CI 165 166 All pull requests will run through CI, which is currently hosted by Circle. 167 Community contributors should be able to see the outcome of this process by looking at the checks on their PR. 168 Please fix any issues to ensure a prompt review from members of the team. 169 170 The InfluxDB project is used internally in a number of proprietary InfluxData products, and as such, PRs and changes need to be tested internally. 171 This can take some time, and is not really visible to community contributors. 172 173 ### Static Analysis 174 175 This project uses the following static analysis tools. 176 Failure during the running of any of these tools results in a failed build. 177 Generally, code must be adjusted to satisfy these tools, though there are exceptions. 178 179 - [go vet](https://golang.org/cmd/vet/) checks for Go code that should be considered incorrect. 180 - [go fmt](https://golang.org/cmd/gofmt/) checks that Go code is correctly formatted. 181 - [go mod tidy](https://tip.golang.org/cmd/go/#hdr-Add_missing_and_remove_unused_modules) ensures that the source code and go.mod agree. 182 - [staticcheck](https://staticcheck.io/docs/) checks for things like: unused code, code that can be simplified, code that is incorrect and code that will have performance issues. 183 184 ### staticcheck 185 186 If your PR fails `staticcheck` it is easy to dig into why it failed, and also to fix the problem. 187 First, take a look at the error message in Circle under the `staticcheck` build section, e.g., 188 189 ``` 190 tsdb/tsm1/encoding.gen.go:1445:24: func BooleanValues.assertOrdered is unused (U1000) 191 tsdb/tsm1/encoding.go:172:7: receiver name should not be an underscore, omit the name if it is unused (ST1006) 192 ``` 193 194 Next, go and take a [look here](http://next.staticcheck.io/docs/checks) for some clarification on the error code that you have received, e.g., `U1000`. 195 The docs will tell you what's wrong, and often what you need to do to fix the issue. 196 197 #### Generated Code 198 199 Sometimes generated code will contain unused code or occasionally that will fail a different check. 200 `staticcheck` allows for [entire files](http://next.staticcheck.io/docs/#ignoring-problems) to be ignored, though it's not ideal. 201 A linter directive, in the form of a comment, must be placed within the generated file. 202 This is problematic because it will be erased if the file is re-generated. 203 Until a better solution comes about, below is the list of generated files that need an ignores comment. 204 If you re-generate a file and find that `staticcheck` has failed, please see this list below for what you need to put back: 205 206 | File | Comment | 207 | :--------------------: | :--------------------------------------------------------------: | 208 | query/promql/promql.go | //lint:file-ignore SA6001 Ignore all unused code, it's generated | 209 210 #### End-to-End Tests 211 212 CI also runs end-to-end tests. These test the integration between the `influxd` server the UI. 213 Since the UI is used by interal repositories as well as the `influxdb` repository, the 214 end-to-end tests cannot be run on forked pull requests or run locally. The extent of end-to-end 215 testing required for forked pull requests will be determined as part of the review process. 216 217 ## Additional Resources 218 - [InfluxDB Tips and Tutorials](https://www.influxdata.com/blog/category/tech/influxdb/) 219 - [InfluxDB Essentials Course](https://university.influxdata.com/courses/influxdb-essentials-tutorial/) 220 - [Exploring InfluxDB Cloud Course](https://university.influxdata.com/courses/exploring-influxdb-cloud-tutorial/)