Skip to content

Commit

Permalink
docs: update CONTRIBUTING.md
Browse files Browse the repository at this point in the history
  • Loading branch information
hiltontj committed Jan 15, 2025
1 parent 26bf912 commit 735f1cc
Showing 1 changed file with 28 additions and 55 deletions.
83 changes: 28 additions & 55 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,10 +34,10 @@ For features we don't plan to support we will close the feature request ticket (

## Contributing Changes

InfluxDB 3 is written mostly in idiomatic Rust—please see the [Style Guide] for more details.
InfluxDB 3 is written mostly in idiomatic Rust. Please refer to the [Rust API Guidelines][rust-api-guide] for more details.
All code must adhere to the `rustfmt` format, and pass all of the `clippy` checks we run in CI (there are more details further down this README).

[Style Guide]: docs/style_guide.md
[rust-api-guide]: https://rust-lang.github.io/api-guidelines/about.html

### Finding Issues To Work On

Expand Down Expand Up @@ -93,76 +93,53 @@ There are some tips on verifying the above in the [next section](#running-tests)

## Running Tests

The `cargo` build tool runs tests as well. Run:
Testing `influxdb3` requires the use of [`cargo-nextest`](https://nexte.st/) which can be installed
via:
```
cargo install cargo-nextest --locked
```

You can then run all tests in the workspace:

```shell
cargo test --workspace
cargo nextest run --workspace
```

### Enabling logging in tests

To enable logging to stderr during a run of `cargo test` set the Rust
`RUST_LOG` environment variable. For example, to see all INFO messages:
To enable logging to stdout/stderr during a run of `cargo nextest` set the Rust `TEST_LOG`, `RUST_LOG`,
and `RUST_LOG_SPAN_EVENTS` environment variables. For example, to see all `INFO` messages:

```shell
RUST_LOG=info cargo test --workspace
TEST_LOG= RUST_LOG=info RUST_LOG_SPAN_EVENTS=full cargo nextest run --workspace --nocapture
```

Since this feature uses
[`EnvFilter`](https://docs.rs/tracing-subscriber/0.2.15/tracing_subscriber/filter/struct.EnvFilter.html) internally, you
can use all the features of that crate. For example, to disable the
(somewhat noisy) logs in some h2 modules, you can use a value of
`TEST_LOG` will emit logs from the running test server (see [End-to-End Tests](#end-to-end-tests))

Since this feature uses [`EnvFilter`][env-filter] internally, you can use all the features of that
crate. For example, to disable the (somewhat noisy) logs in some h2 modules, you can use a value of
`RUST_LOG` such as:

```shell
RUST_LOG=debug,hyper::proto::h1=info,h2=info cargo test --workspace
RUST_LOG=debug,hyper::proto::h1=info,h2=info RUST_LOG_SPAN_EVENTS=full cargo nextest run --workspace --nocapture
```

See [logging.md](docs/logging.md) for more information on logging.

### End-to-End Tests

There are end-to-end tests that spin up a server and make requests via the client library and API. They can be found in `tests/end_to_end_cases`
Many tests use the [`test-log`](https://crates.io/crates/test-log) crate to enable this logging
behaviour, which requires the use of the `RUST_LOG_SPAN_EVENTS` environment variable.

These require additional setup as described in [testing.md](docs/testing.md).
[env-filter]: https://docs.rs/tracing-subscriber/0.2.15/tracing_subscriber/filter/struct.EnvFilter.html

### Visually showing explain plans
### End-to-End Tests

Some query plans are output in the log in [graphviz](https://graphviz.org/) format. To display them you can use the `tools/iplan` helper.
There are end-to-end tests that spin up a server and make requests via the client library and API.
They can be found in `influxdb3/tests/`

For example, if you want to display this plan:
When running these tests, you can have the logs of the running server emitted to stdout by adding
the `TEST_LOG` environment variable, for example:

```shell
TEST_LOG= cargo nextest run -p influxdb3 --nocapture
```
// Begin DataFusion GraphViz Plan (see https://graphviz.org)
digraph {
subgraph cluster_1
{
graph[label="LogicalPlan"]
2[shape=box label="SchemaPivot"]
3[shape=box label="Projection: "]
2 -> 3 [arrowhead=none, arrowtail=normal, dir=back]
4[shape=box label="Filter: Int64(0) LtEq #time And #time Lt Int64(10000) And #host Eq Utf8(_server01_)"]
3 -> 4 [arrowhead=none, arrowtail=normal, dir=back]
5[shape=box label="TableScan: attributes projection=None"]
4 -> 5 [arrowhead=none, arrowtail=normal, dir=back]
}
subgraph cluster_6
{
graph[label="Detailed LogicalPlan"]
7[shape=box label="SchemaPivot\nSchema: [non_null_column:Utf8]"]
8[shape=box label="Projection: \nSchema: []"]
7 -> 8 [arrowhead=none, arrowtail=normal, dir=back]
9[shape=box label="Filter: Int64(0) LtEq #time And #time Lt Int64(10000) And #host Eq Utf8(_server01_)\nSchema: [color:Utf8;N, time:Int64]"]
8 -> 9 [arrowhead=none, arrowtail=normal, dir=back]
10[shape=box label="TableScan: attributes projection=None\nSchema: [color:Utf8;N, time:Int64]"]
9 -> 10 [arrowhead=none, arrowtail=normal, dir=back]
}
}
// End DataFusion GraphViz Plan
```

You can pipe it to `iplan` and render as a .pdf


## Running `rustfmt` and `clippy`

Expand Down Expand Up @@ -194,7 +171,3 @@ cargo clippy --all-targets --workspace -- -D warnings

[`rustfmt`]: https://github.com/rust-lang/rustfmt
[`clippy`]: https://github.com/rust-lang/rust-clippy

## Distributed Tracing

See [tracing.md](docs/tracing.md) for more information on the distributed tracing functionality within InfluxDB 3

0 comments on commit 735f1cc

Please sign in to comment.