github.com/influxdata/influxdb/v2@v2.7.6/CONTRIBUTING.md (about) 1 # Contributing to InfluxDB v2 2 3 ## How to report a bug 4 5 Before you report an issue, please [search existing issues](https://github.com/influxdata/influxdb/issues) to check whether it's 6 already been reported, or perhaps even fixed. 7 If you choose to report an issue, please include the following in your report: 8 9 - Full details of your operating system (or distribution)--for example, `64bit Ubuntu 18.04`. 10 To get your operating system details, run the following command in your terminal 11 and copy-paste the output into your report: 12 13 ```sh 14 uname -srm 15 ``` 16 - How you installed InfluxDB. Did you use a pre-built package or did you build from source? 17 - The version of InfluxDB you're running. 18 If you installed InfluxDB using a pre-built package, run the following command in your terminal and then copy-paste the output into your report: 19 20 ```sh 21 influxd version 22 ``` 23 24 If you built and ran `influxd` from source, run the following command from your *influxdb* directory and then copy-paste the output into your report: 25 26 ```sh 27 bin/$(uname -s | tr '[:upper:]' '[:lower:]')/influxd version 28 ``` 29 - [Clear steps to reproduce the issue](#how-to-provide-steps-to-reproduce-an-issue) 30 31 ### How to provide steps for reproducing an issue 32 33 The easier we can reproduce the problem, the easier we can fix it. 34 To learn how to write an effective bug report, we recommend reading [Simon Tatham's essay, "How to Report Bugs Effectively."](http://www.chiark.greenend.org.uk/~sgtatham/bugs.html). 35 36 When describing how to reproduce the issue, 37 please provide test cases in the form of `curl` commands--for example: 38 39 ```bash 40 # write data 41 curl -XPOST "http://localhost:8086/api/v2/write?org=YOUR_ORG&bucket=YOUR_BUCKET&precision=s" \ 42 --header "Authorization: Token YOURAUTHTOKEN" \ 43 --data-raw "mem,host=host1 used_percent=23.43234543 1556896326" 44 45 # query data 46 # Bug: expected it to return no data, but data comes back. 47 curl http://localhost:8086/api/v2/query?org=my-org -XPOST -sS \ 48 -H 'Authorization: Token YOURAUTHTOKEN' \ 49 -H 'Accept: application/csv' \ 50 -H 'Content-type: application/vnd.flux' \ 51 -d 'from(bucket:"example-bucket") 52 |> range(start:-1000h) 53 |> group(columns:["_measurement"], mode:"by") 54 |> sum()' 55 ``` 56 57 Test cases with `influx` CLI commands are also helpful--for example: 58 59 ``` 60 # write data 61 influx write -o YOUR_ORG -b YOUR_BUCKET -p s -t YOURAUTHTOKEN \ 62 "mem,host=host1 used_percent=23.43234543 1556896326" 63 64 # query data 65 # Bug: expected it to return no data, but data comes back. 66 influx query -o YOUR_ORG -t YOURAUTHTOKEN 'from(bucket:"example-bucket") 67 |> range(start:-1000h) 68 |> group(columns:["_measurement"], mode:"by") 69 |> sum()' 70 ``` 71 72 If you don't provide clear test cases like the examples above, then investigating your issue will be very difficult for us. 73 If you have trouble including data in your report, please zip up your data directory and include a link to it in your bug report. 74 75 Note that issues are _not the place to file general support requests_ such as "How do I use `collectd` with InfluxDB?" 76 Please submit requests for help to the [InfluxData Community](https://community.influxdata.com/) - don't report them as issues in the repo. 77 78 ## How to request a feature 79 80 We encourage you to submit feature requests as they help us prioritize our work. 81 82 In your feature request, please include the following: 83 - Clear requirements and goals. 84 - What you would like to see added to InfluxDB. 85 - Examples. 86 - Why the feature is important to you. 87 88 If you find your request already exists in a Github issue, 89 please indicate your support for the existing issue by using the "thumbs up" reaction. 90 91 ## How to submit a pull (change) request 92 93 To submit a change for code or documentation in this repository, please [create a pull request](https://github.com/influxdata/influxdb/compare) and follow the instructions in the pull request template to help us review your PR. 94 After you complete the template steps and submit the PR, expect some deliberation as we review and finalize the change. 95 Once your PR is approved, you can merge it. 96 97 ## How to report security vulnerabilities 98 99 InfluxData takes security and our users' trust very seriously. 100 If you believe you have found a security issue in any of our open source projects, please responsibly disclose it by contacting security@influxdata.com. 101 More details about security vulnerability reporting, including our GPG key, [can be found here](https://www.influxdata.com/how-to-report-security-vulnerabilities/). 102 103 ## Signing the CLA 104 105 Before you contribute to InfluxDB, please sign our [Individual Contributor License Agreement (CLA)](https://influxdata.com/community/cla/). 106 107 ## How to build InfluxDB from source 108 109 ### Install Go 110 111 InfluxDB requires Go 1.18. 112 113 At InfluxData we find `gvm`, a Go version manager, useful for installing Go. 114 For instructions on how to install it see [the gvm page on github](https://github.com/moovweb/gvm). 115 116 After installing `gvm` you can install and set the default Go version by running the following: 117 118 ```bash 119 $ gvm install go1.18 120 $ gvm use go1.18 --default 121 ``` 122 123 InfluxDB requires Go module support. Set `GO111MODULE=on` or build the project outside of your `GOPATH` for it to succeed. For information about modules, please refer to the [wiki](https://github.com/golang/go/wiki/Modules). 124 125 ### Install revision control systems 126 127 Go has the ability to import remote packages via revision control systems with the `go get` command. 128 To ensure that you can retrieve any remote package, install `git` and `bzr` revision control software, following the instructions for your system: 129 130 - [Install Git](http://git-scm.com/book/en/Getting-Started-Installing-Git) 131 - [Install Bazaar](http://doc.bazaar.canonical.com/latest/en/user-guide/installing_bazaar.html) 132 133 ### Install additional dependencies 134 135 In addition to `go`, `git`, and `bzr`, you will need the following prerequisites 136 installed on your system: 137 138 - Rust (a recent stable version, 1.60 or higher). 139 To install Rust, we recommend using [rustup](https://rustup.rs/). 140 - `clang` 141 - `make` 142 - `pkg-config` 143 - `protobuf` 144 - Go protobuf plugin. To use Go to install the plugin, enter the following command in your terminal: 145 146 `go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28` 147 148 To install prerequisites, use the following example command for your system: 149 150 - OSX: `brew install pkg-config protobuf` 151 - For OSX, you must have [HomeBrew](https://brew.sh) installed. 152 - You will also need the [Developer Tools](https://webkit.org/build-tools/), which includes `make`. 153 - Linux (Arch): `pacman -S clang make pkgconf protobuf` 154 - Linux (Ubuntu): `sudo apt install make clang pkg-config protobuf-compiler libprotobuf-dev build-essential` 155 - Linux (RHEL): see the [RedHat-specific instructions](#redhat-specific-instructions). 156 157 #### RedHat-specific instructions 158 159 For RedHat, you must enable the [EPEL](https://fedoraproject.org/wiki/EPEL) 160 161 ### Build influxd with make 162 163 `influxd` is the InfluxDB service. 164 165 For `influx`, the InfluxDB CLI tool, see the [influx-cli repository on Github](https://github.com/influxdata/influx-cli). 166 167 Once you've installed the dependencies, 168 follow these steps to build `influxd` from source and start the service: 169 170 1. Clone this repo (influxdb). 171 2. In your influxdb directory, run `make` to generate the influxd binary: 172 173 ```sh 174 make 175 ``` 176 177 If successful, `make` installs the binary to a platform-specific path for your system. 178 The output is the following: 179 180 ```sh 181 env GO111MODULE=on go build -tags 'assets ' -o bin/$(uname -s | tr '[:upper:]' '[:lower:]')/influxd ./cmd/influxd 182 ``` 183 184 3. To start the `influxd` service that runs InfluxDB, enter the following command 185 to run the platform-specific binary: 186 187 ``` 188 bin/$(uname -s | tr '[:upper:]' '[:lower:]')/influxd 189 ``` 190 191 `influxd` logs to `stdout` by default. 192 193 **Troubleshooting** 194 195 - If you've changed Go or Rust versions and have trouble building, try running `go clean -r -x -cache -testcache -modcache ./` to clear out old build artifacts that may be incompatible. 196 197 ### Run tests 198 199 This project is built from various languages. 200 To run tests for all languages and components, enter the following command in 201 your terminal: 202 203 ```bash 204 make test 205 ``` 206 207 To run tests for only Go and Rust components, enter the following command in your terminal: 208 209 ```bash 210 make test-go 211 ``` 212 213 ## Generated Google Protobuf code 214 215 Most changes to the source don't require changes to the generated protocol buffer code. 216 If you need to modify the protocol buffer code, you'll first need to install the protocol buffers toolchain. 217 218 First install the [protocol buffer compiler](https://developers.google.com/protocol-buffers/) 3.17.3 or later for your OS. 219 220 Then run `go generate` after updating any `*.proto` file: 221 222 ```bash 223 go generate ./... 224 ``` 225 226 **How to troubleshoot protobuf** 227 228 If generating the protobuf code is failing for you, check each of the following: 229 230 - Ensure the protobuf library can be found. Make sure that `LD_LIBRARY_PATH` includes the directory in which the library `libprotoc.so` has been installed. 231 - Ensure the command `protoc-gen-go`, found in `GOPATH/bin`, is on your path. This can be done by adding `GOPATH/bin` to `PATH`. 232 233 ## Generated Go Templates 234 235 The query engine requires optimized data structures for each data type so instead of writing each implementation several times we use templates. 236 _Do not change code that ends in a `.gen.go` extension!_ 237 Instead you must edit the `.gen.go.tmpl` file that was used to generate it. 238 239 Once you've edited the template file, you'll need the [`tmpl`][tmpl] utility to generate the code: 240 241 ```sh 242 $ go get github.com/benbjohnson/tmpl 243 ``` 244 245 Then you can regenerate all templates in the project: 246 247 ```sh 248 $ go generate ./... 249 ``` 250 251 [tmpl]: https://github.com/benbjohnson/tmpl 252 253 ## Profiling 254 255 When troubleshooting problems with CPU or memory the Go toolchain can be helpful. 256 You can start InfluxDB with CPU and memory profiling turned on. 257 For example: 258 259 ```bash 260 # start influx with profiling 261 262 $ ./influxd -cpuprofile influxdcpu.prof -memprof influxdmem.prof 263 264 # run queries, writes, whatever you're testing 265 # Quit out of influxd and influxd.prof will then be written. 266 # open up pprof to examine the profiling data. 267 268 $ go tool pprof ./influxd influxd.prof 269 270 # once inside run "web", opens up browser with the CPU graph 271 # can also run "web <function name>" to zoom in. Or "list <function name>" to see specific lines 272 ``` 273 274 Note that when you pass the binary to `go tool pprof` _you must specify the path to the binary_. 275 276 If you are profiling benchmarks built with the `testing` package, you may wish 277 to use the [`github.com/pkg/profile`](github.com/pkg/profile) package to limit 278 the code being profiled: 279 280 ```go 281 func BenchmarkSomething(b *testing.B) { 282 // do something intensive like fill database with data... 283 defer profile.Start(profile.ProfilePath("/tmp"), profile.MemProfile).Stop() 284 // do something that you want to profile... 285 } 286 ```