Skip to content

Commit bd8f7c6

Browse files
author
John Del Castillo
committed
Updated readme, added test doco
1 parent 1c5685c commit bd8f7c6

File tree

1 file changed

+138
-4
lines changed

1 file changed

+138
-4
lines changed

‎README.md‎

Lines changed: 138 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -33,13 +33,17 @@ For example, the following PromQL query will return an estimate of the number of
3333

3434
## Compatibility
3535

36-
*cassandra-exporter* is has been tested with:
36+
*cassandra-exporter* is now Cassandra 4.0+ compatible, but the change is not a backwards compatible. Support for older Cassandra versions is via the older releases, as follows:
3737

38-
| Component | Version |
38+
| Cassandra Version | Compatible Exporter Version |
3939
|-----------------|---------------|
40-
| Apache Cassandra| 3.0.17 (experimental), 3.11.2, 3.11.3 |
41-
| Prometheus | 2.0 and later |
40+
| Apache Cassandra 4.x | 0.9.12 |
41+
| Apache Cassandra 3.0.17, 3.11.2, 3.11.3 | 0.9.11 |
4242

43+
| Prometheus Version |
44+
|-----------------|
45+
| 2.42.0
46+
|
4347
Other Cassandra and Prometheus versions will be tested for compatibility in the future.
4448

4549
## Usage
@@ -407,6 +411,136 @@ We suggest viewing the metrics endpoint (e.g., <http://localhost:9500/metrics>)
407411
are exported by your Cassandra node.
408412

409413

414+
## Testing
415+
416+
### Java
417+
There are unit tests in the various projects which will get executed with the maven commands.
418+
419+
### Integration test harness
420+
421+
There is an integration test harness available in the */test/* folder.
422+
423+
#### Requirements
424+
425+
The test harness uses Python (tested with 3.10).
426+
427+
Initialise the project by using the pyproject.toml file
428+
429+
pip install .
430+
431+
The tool can be launched via
432+
433+
python test_tool.py
434+
435+
#### Operation
436+
437+
There are four modes of operation:
438+
439+
- `benchmark`
440+
441+
Not Implemented - TBA - Intended to test the speed of collection.
442+
443+
- `demo`
444+
445+
Usage: test_tool.py demo [OPTIONS]
446+
447+
Start a Cassandra cluster with cassandra-exporter installed (agent or
448+
standalone). Optionally setup a schema. Wait for ctrl-c to shut everything
449+
down.
450+
451+
Working Directory:
452+
-C, --working-directory PATH location to install Cassandra and/or Prometheus.
453+
Must be empty or not exist. Defaults to a
454+
temporary directory.
455+
--cleanup-working-directory [on-error|always|never]
456+
how to delete the working directory on exit:
457+
"on-error": delete working directory on exit
458+
unless an error occurs, "always": always delete
459+
working directory on exit, "never": never delete
460+
working directory. [default: on-error]
461+
462+
Cassandra:
463+
--cluster-name TEXT name of the Cassandra cluster [default: test-
464+
cluster]
465+
--cassandra-version TEXT Cassandra version to run [default: 4.1.0]
466+
--topology DCS RACKS NODES number of data centers, racks per data center,
467+
and nodes per rack. [default: 2, 3, 1]
468+
-j, --exporter-jar PATH path of the cassandra-exporter jar to use,
469+
either agent or standalone builds, or one of
470+
"agent" or "standalone" for the currently built
471+
jar of that type in the project directory
472+
(assumes that the sources for this test tool are
473+
in the standard location within the project, and
474+
that the jar(s) have been built). [default:
475+
agent]
476+
-s, --schema PATH path of the CQL schema YAML file to apply on
477+
cluster start. The YAML file must contain a list
478+
of CQL statement strings, which are applied in
479+
order. [default: /root/source/forks/cassandra-
480+
exporter/test/schema.yaml]
481+
482+
- `dump`
483+
484+
Usage: test_tool.py dump [OPTIONS] COMMAND [ARGS]...
485+
486+
Commands to capture, validate and diff metrics dumps
487+
488+
Options:
489+
--help Show this message and exit.
490+
491+
Commands:
492+
capture Start a Cassandra cluster, capture metrics from each node's...
493+
diff Compare two metrics dumps and output the difference
494+
validate Validate a metrics dump using Prometheus's promtool.
495+
496+
- `e2e` - *Note no tests are run at the moment*
497+
498+
Usage: test_tool.py e2e [OPTIONS]
499+
500+
Run cassandra-exporter end-to-end tests.
501+
502+
- Start C* with the exporter JAR (agent or standalone).
503+
- Setup a schema.
504+
- Configure and start prometheus.
505+
- Wait for all scrape targets to get healthy.
506+
- Run some tests.
507+
508+
Working Directory:
509+
-C, --working-directory PATH location to install Cassandra and/or
510+
Prometheus. Must be empty or not exist.
511+
Defaults to a temporary directory.
512+
--cleanup-working-directory [on-error|always|never]
513+
how to delete the working directory on exit:
514+
"on-error": delete working directory on exit
515+
unless an error occurs, "always": always delete
516+
working directory on exit, "never": never
517+
delete working directory. [default: on-error]
518+
519+
Cassandra:
520+
--cluster-name TEXT name of the Cassandra cluster [default: test-
521+
cluster]
522+
--cassandra-version TEXT Cassandra version to run [default: 4.1.0]
523+
--topology DCS RACKS NODES number of data centers, racks per data center,
524+
and nodes per rack. [default: 2, 3, 1]
525+
-j, --exporter-jar PATH path of the cassandra-exporter jar to use,
526+
either agent or standalone builds, or one of
527+
"agent" or "standalone" for the currently built
528+
jar of that type in the project directory
529+
(assumes that the sources for this test tool
530+
are in the standard location within the
531+
project, and that the jar(s) have been built).
532+
[default: agent]
533+
-s, --schema PATH path of the CQL schema YAML file to apply on
534+
cluster start. The YAML file must contain a
535+
list of CQL statement strings, which are
536+
applied in order. [default:
537+
/root/source/forks/cassandra-
538+
exporter/test/schema.yaml]
539+
540+
Prometheus Archive: [mutually exclusive]
541+
--prometheus-version TAG
542+
--prometheus-archive PATH/URL
543+
410544
## Unstable, Missing & Future Features
411545

412546
See the [project issue tracker](https://github.com/instaclustr/cassandra-exporter/issues) for a complete list.

0 commit comments

Comments
 (0)