9.7 KiB

Raw Permalink Blame History

Contributing to InfluxDB v2

Report a bug

Before you file an issue, please search existing issues to see if it's been filed (or fixed). If you file an issue, please include the following:

Full details of your operating system (or distribution) e.g. 64bit Ubuntu 18.04.
The version of InfluxDB you're running.
Whether you installed InfluxDB from a pre-built package, or built it from source.
Clear steps to reproduce the issue described, if possible.

The easier for us to reproduce the problem, the easier we can fix it. If you've never written a bug report before, or want to brush up on your bug reporting skills, we recommend reading Simon Tatham's essay "How to Report Bugs Effectively."

Please provide tests in the form of curl commands, as in the following example:

# write data
curl -XPOST "http://localhost:8086/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"

# query data
# Bug: expected it to return no data, but data comes back.
curl http://localhost:8086/api/v2/query?org=my-org -XPOST -sS \
  -H 'Authorization: Token YOURAUTHTOKEN' \
  -H 'Accept: application/csv' \
  -H 'Content-type: application/vnd.flux' \
  -d 'from(bucket:"example-bucket")
    |> range(start:-1000h)
    |> group(columns:["_measurement"], mode:"by")
    |> sum()'

Test cases with influx commands are also helpful, as in the following example:

# write data
influx write -o YOUR_ORG -b YOUR_BUCKET -p s -t YOURAUTHTOKEN \
  "mem,host=host1 used_percent=23.43234543 1556896326"

# query data
# Bug: expected it to return no data, but data comes back.
influx query -o YOUR_ORG -t YOURAUTHTOKEN 'from(bucket:"example-bucket")
  |> range(start:-1000h)
  |> group(columns:["_measurement"], mode:"by")
  |> sum()'

If you don't include a clear test case like the example above, we won't be able to investigate your issue as quickly. If writing the data is too difficult, please zip up your data directory and include a link to it in your bug report.

Please note that issues are not the place to file general support requests. Please send support questions like "How do I use collectd with InfluxDB?" to the InfluxData Community, not to Github issues.

Request a feature

We welcome your feature requests as they help us prioritize our work. When submitting feature requests, please keep the following in mind:

Be clear about your requirements and goals.
Provide examples of the enhancement that you would like to see and tell us why it's important to you.
If you find your feature request already exists as a Github issue, please add a "thumbs up" reaction to indicate your support for that feature.

Submit a pull request

To submit a pull request, follow these steps:

Fork the influxdata/influxdb repository.
Checkout a feature branch in your fork.
In your feature branch, make your change and run the test suite (given you won't be able to merge if tests fail).
Commit your change.
Generate a pull request (PR) from your branch against the master branch of influxdata/influxdb.
In your PR, provide details of your change--the why and the how--as well as the testing you performed.
Expect some deliberation as we finalize the change, but once that completes it may be merged.

To help our review, please add the following in your PR comment:

- [ ] CHANGELOG.md updated
- [ ] Rebased/mergable
- [ ] Tests pass
- [ ] Sign [CLA](https://influxdata.com/community/cla/) (if not already signed)

Report security vulnerabilities

InfluxDB 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 security@influxdata.com. For more information, see how to report security vulnerabilities.

Sign the CLA

Before you contribute to InfluxDB, take a second to sign our CLA, which can be found on our website.

Build InfluxDB from Source

Install Go

InfluxDB requires Go 1.18.

At InfluxData, we use the gvm Go version manager to install Go. For installation instructions, see the gvm page on github.

With gvm installed, run the following commands to install the required go version and set it as the default.

gvm install go1.18
gvm use go1.18 --default

InfluxDB requires Go module support. Set GO111MODULE=on or build the project outside your GOPATH for it to succeed. For more information about modules, see the Go wiki.

Install revision control systems

With the go get command, you can import remote Go packages from revision control systems (RCS). To install git and bzr RCS for InfluxDB, follow the instructions:

Install additional dependencies

With the revision control systems installed, you're ready to install the remaining dependencies.

You need a recent stable version of Rust. We recommend using rustup to install Rust.

You also need clang, make, pkg-config, and protobuf installed.

macOS:
1. Install HomeBrew (which provides brew) and Developer Tools (which provides make).
2. Run brew install pkg-config protobuf
Linux (Arch): pacman -S clang make pkgconf protobuf
Linux (Ubuntu): sudo apt install make clang pkg-config protobuf-compiler libprotobuf-dev
Linux (RHEL): See below

RedHat-specific instructions

For RedHat, you must enable the EPEL

Build influxd with make

influxd is the InfluxDB service.

For influx, the InfluxDB CLI tool, see the influx-cli repository on Github.

Once you've installed the dependencies, follow these steps to build influxd from source and start the service:

Clone this repo (influxdb).
In your influxdb directory, run make to encode dependencies.
```
make
```

Run the following go build command to compile the influxd binary at a platform-dependent path.

env GO111MODULE=on go build -tags 'assets ' -o bin/$(uname -s | tr '[:upper:]' '[:lower:]')/influxd ./cmd/influxd

Start the influxd service.

bin/$(uname -s | tr '[:upper:]' '[:lower:]')/influxd

influxd logs to stdout by default.

Run tests

This project is built from various languages. To run tests for all languages and components, run the following:

make test

To run tests for only Go/Rust components, run the following:

make test-go

Generated Google Protobuf code

Most changes to the source do not require that the generated protocol buffer code be changed. But if you need to modify the protocol buffer code, you'll first need to install the protocol buffers toolchain.

First install the protocol buffer compiler 3.17.3 or later for your OS.

Then run go generate after updating any *.proto file:

go generate ./...

Troubleshoot protobuf

If generating the protobuf code is failing for you, check the following:

Ensure Go can find the protobuf library on your system--check that LD_LIBRARY_PATH includes the directory where the libprotoc.so library is installed.
Ensure the protoc-gen-go executable in GOPATH/bin is on your system path by adding GOPATH/bin to PATH.

Generated Go Templates

The query engine requires optimized data structures for each data type so instead of writing each implementation several times, we use templates. Do not change code that ends in a .gen.go extension! Instead, edit the .gen.go.tmpl file that was used to generate it.

Once you've edited the template file, you'll need the tmpl utility to generate the code:

go get github.com/benbjohnson/tmpl

Then you can regenerate all templates in the project:

go generate ./...

Profiling

Go profiling tools can help you troubleshoot problems with CPU or memory. To start InfluxDB with CPU and memory profiling enabled, pass the profiling flags, as in the following example:

# Start influx with profiling.

$ ./influxd -cpuprofile influxdcpu.prof -memprof influxdmem.prof

# Run queries, writes, or whatever you're testing.
# Quit out of influxd and influxd.prof will then be written.
# Run pprof to examine the profiling data.

$ go tool pprof ./influxd influxd.prof

# At the prompt, run "web" to view the CPU graph in a browser.
# To zoom in, run "web <function name>".
# To see specific lines, run "list <function name>".

Note that when you pass the binary to go tool pprof you must specify the path to the binary.

If you are profiling benchmarks built with the testing package, you may wish to use the github.com/pkg/profile package to limit the code being profiled:

func BenchmarkSomething(b *testing.B) {
  // do something intensive like fill database with data...
  defer profile.Start(profile.ProfilePath("/tmp"), profile.MemProfile).Stop()
  // do something that you want to profile...
}

To learn more about profiling and debugging in InfluxDB, see InfluxDB OSS runtime.

9.7 KiB Raw Permalink Blame History