From 905dfe912499b77198d1cd19e76b8cff693d417b Mon Sep 17 00:00:00 2001 From: Doug Hoard Date: Mon, 2 Dec 2024 17:34:08 -0500 Subject: [PATCH] Update documentation (#1079) * Updated documentation Signed-off-by: dhoard --- docs/content/1.1.0/_index.md | 2 +- docs/content/1.1.0/building_testing/_index.md | 32 +++++++++++-------- docs/content/1.1.0/contributing.md | 29 +++++++++++++++++ docs/content/1.1.0/license.md | 8 +++++ docs/content/1.1.0/standalone/_index.md | 2 +- docs/content/_index.md | 16 ++++++++++ 6 files changed, 73 insertions(+), 16 deletions(-) create mode 100644 docs/content/1.1.0/contributing.md create mode 100644 docs/content/1.1.0/license.md create mode 100644 docs/content/_index.md diff --git a/docs/content/1.1.0/_index.md b/docs/content/1.1.0/_index.md index 723bea47..4b3a1e6c 100644 --- a/docs/content/1.1.0/_index.md +++ b/docs/content/1.1.0/_index.md @@ -1,5 +1,5 @@ --- -title: "Version 1.1.0" +title: "JMX Exporter 1.1.0" weight: 1 --- diff --git a/docs/content/1.1.0/building_testing/_index.md b/docs/content/1.1.0/building_testing/_index.md index 04548cb3..2c208ac4 100644 --- a/docs/content/1.1.0/building_testing/_index.md +++ b/docs/content/1.1.0/building_testing/_index.md @@ -3,9 +3,9 @@ title: "Building / Testing" weight: 4 --- -The JMX Exporter requires Java 11+ to build and test the code. +Java 11+ is required to build and unit test the code. -Docker is required to run integration tests. +Docker is required to run the integration test suite. ## Building (unit tests only) @@ -41,13 +41,15 @@ cd jmx_exporter ## Integration Testing (smoke test containers) +Integration tests use [Verifyica](https://github.com/verifyica-team/verifyica) for integration testing. + +Integration tests require Docker configuration changes due to parallel testing/the number of Docker networks used during testing. + **Integration testing time using smoke test containers varies based on your machine specifications.** -- **~7 minutes on an AMD Ryzen 9 7900 + NVMe** +- **~7 minutes on an AMD Ryzen 9 7900 with an NVMe drive** - **~20 minutes using a standard GitHub action runner** -Integration tests require Docker configuration changes due to parallel testing/the number of Docker networks used during testing. - **Notes** - You may need to set up your Docker hub login to pull images @@ -88,9 +90,9 @@ cd jmx_exporter **Notes** -The `smoke-test.sh` shell script can be used to build and run integration tests using smoke test containers. - -Output is captured and logged to `smoke-test.log`. +- The `smoke-test.sh` shell script can be used to build and run the integration test suite using smoke test containers. + - `./smoke-test.sh` +- Output is captured and logged to `smoke-test.log`. ### Example Output @@ -131,14 +133,16 @@ Output is captured and logged to `smoke-test.log`. ## Integration Tests (all test containers) +Integration tests use [Verifyica](https://github.com/verifyica-team/verifyica) for integration testing. + +Integration tests require Docker configuration changes due to parallel testing/the number of Docker networks used during testing. + **Integration testing using all test containers requires SIGNIFICANT time and disk space.** -- **~100 Docker containers (Java + Prometheus)** +- **~100 Docker containers (Java and Prometheus containers)** - **~2 hours on an AMD Ryzen 9 7900 + NVMe** - **3+ hours on a Dual Intel Xeon CPU E5-2680 v4** -Integration tests require Docker configuration changes due to parallel testing/the number of Docker networks used during testing. - **Notes** - You may need to set up your Docker hub login to pull images @@ -181,9 +185,9 @@ cd jmx_exporter **Notes** -The `regression-test.sh` shell script can be used to build and run integration tests using all test containers. - -Output is captured and logged to `regression-test.log`. +- The `regression-test.sh` shell script can be used to build and run the integration test suite using all test containers. + - `./regression-test.sh` +- Output is captured and logged to `regression-test.log`. ### Output diff --git a/docs/content/1.1.0/contributing.md b/docs/content/1.1.0/contributing.md new file mode 100644 index 00000000..efd75d78 --- /dev/null +++ b/docs/content/1.1.0/contributing.md @@ -0,0 +1,29 @@ +--- +title: "Contributing" +weight: 5 +--- + +The JMX Exporter uses GitHub to manage issues and reviews of pull requests. + +### Trivial Fixes / Improvements + +If you have a trivial fix or improvement, go ahead and create a pull request, tagging the maintainers. + +- [MAINTAINERS.md](https://github.com/prometheus/jmx_exporter/blob/main/MAINTAINERS.md) + +### Advanced Fixes / Improvements + +If you plan to do something more involved, first discuss your ideas on the [mailing list](https://groups.google.com/forum/?fromgroups#!forum/prometheus-developers). + +This will avoid unnecessary work and surely give you and us a good deal of inspiration. + +### Code Formatting + +Code formatting is enforced using the [Maven Spotless Plugin](https://github.com/diffplug/spotless/tree/main/plugin-maven) along with [Google Java Format](https://github.com/google/google-java-format) as part of the build. + +### Branch Strategy + +[GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow) is used for branching. + +- Pull requests should be opened against `main` for the next release. + diff --git a/docs/content/1.1.0/license.md b/docs/content/1.1.0/license.md new file mode 100644 index 00000000..481586d5 --- /dev/null +++ b/docs/content/1.1.0/license.md @@ -0,0 +1,8 @@ +--- +title: "License" +weight: 6 +--- + +The JMX Exporter is licensed under the Apache License 2.0. + +- [LICENSE](https://github.com/prometheus/jmx_exporter/blob/main/LICENSE) \ No newline at end of file diff --git a/docs/content/1.1.0/standalone/_index.md b/docs/content/1.1.0/standalone/_index.md index c9342876..5e0ab28c 100644 --- a/docs/content/1.1.0/standalone/_index.md +++ b/docs/content/1.1.0/standalone/_index.md @@ -3,7 +3,7 @@ title: Standalone weight: 2 --- -The Standalone JMX Exporter jar runs as a separate application that connects to your application using RMI and collects metrics. +The Standalone JMX Exporter runs as a separate application that connects to your application using RMI and collects JMX MBean metrics. **Use of the JMX Exporter Java agent is strongly encouraged due to the complex application RMI configuration required when running the Standalone JMX Exporter.** diff --git a/docs/content/_index.md b/docs/content/_index.md new file mode 100644 index 00000000..4e8f6fd3 --- /dev/null +++ b/docs/content/_index.md @@ -0,0 +1,16 @@ +--- +title: "JMX Exporter" +weight: 1 +--- + +The JMX Exporter is a pair collectors to capture JMX MBean metric values. + +### Java Agent + +The JMX Exporter Java agent provides access to JMX metrics running as a Java agent within your application. + +**Use of the JMX Exporter Java agent is strongly encouraged due to the complex application RMI configuration required when running the Standalone JMX Exporter.** + +### Standalone + +The Standalone JMX Exporter runs as a separate application that connects to your application using RMI and collects JMX MBean metrics. \ No newline at end of file