Skip to content

Commit 32745a5

Browse files
dhoarddhoard
authored
1.2.0 documentation (#1153)
Signed-off-by: dhoard <[email protected]>
1 parent ec9f46d commit 32745a5

File tree

18 files changed

+1135
-0
lines changed

18 files changed

+1135
-0
lines changed

‎docs/content/1.2.0/_index.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
title: "JMX Exporter 1.2.0"
3+
weight: 1
4+
geekdocCollapseSection: true
5+
---
6+
7+
This is the documentation for the [Prometheus JMX Exporter](https://github.com/prometheus/jmx_exporter) version 1.2.0.
8+
9+
The main new features of the 1.2.0 release are:
10+
11+
* **OpenTelemetry** Push metrics in OTLP format to an OpenTelemetry endpoint
12+
* **Pluggable Authenticator** Ability to integrate a custom pluggable authenticator
13+
14+
**Documentation and Examples**
15+
16+
Community provided example YAML configuration files:
17+
18+
- [examples](https://github.com/prometheus/jmx_exporter/tree/main/examples)
19+
20+
Integration tests also provide complex/concrete examples of application and YAML configuration files:
21+
22+
- [integration_test_suite/integration_tests/src/test/resources/io/prometheus/jmx/test](https://github.com/prometheus/jmx_exporter/tree/main/integration_test_suite/integration_tests/src/test/resources/io/prometheus/jmx/test)

‎docs/content/1.2.0/building_testing/_index.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
---
2+
title: "Building / Testing"
3+
weight: 4
4+
---
5+
6+
Java 11+ is required to build and test the code.
7+
8+
Docker is required to run the integration test suite.
9+
10+
## Building (unit tests only)
11+
12+
### Commands
13+
14+
```shell
15+
git clone https://github.com/prometheus/jmx_exporter
16+
cd jmx_exporter
17+
./mvnw clean package
18+
```
19+
20+
### Example Output
21+
22+
```shell
23+
...
24+
[INFO] Reactor Summary for Prometheus JMX Exporter <VERSION>:
25+
[INFO]
26+
[INFO] Prometheus JMX Exporter ............................ SUCCESS [ 1.049 s]
27+
[INFO] Prometheus JMX Exporter - Collector ................ SUCCESS [ 12.947 s]
28+
[INFO] Prometheus JMX Exporter - Common ................... SUCCESS [ 3.792 s]
29+
[INFO] Prometheus JMX Exporter - Java Agent ............... SUCCESS [ 44.846 s]
30+
[INFO] Prometheus JMX Exporter - Standalone Server ........ SUCCESS [ 7.049 s]
31+
[INFO] Prometheus JMX Exporter - Integration Test Suite ... SUCCESS [ 0.278 s]
32+
[INFO] Prometheus JMX Exporter - JMX Example Application .. SUCCESS [ 1.925 s]
33+
[INFO] Prometheus JMX Exporter - Integration Tests ........ SUCCESS [ 4.505 s]
34+
[INFO] ------------------------------------------------------------------------
35+
[INFO] BUILD SUCCESS
36+
[INFO] ------------------------------------------------------------------------
37+
[INFO] Total time: 01:17 min
38+
[INFO] Finished at: 2024-12-02T13:39:20-05:00
39+
[INFO] ------------------------------------------------------------------------
40+
```
41+
42+
## Integration Testing (smoke test containers)
43+
44+
Integration tests use [Verifyica](https://github.com/verifyica-team/verifyica) for integration testing.
45+
46+
Integration tests require Docker configuration changes due to parallel testing/the number of Docker networks used during testing.
47+
48+
**Integration testing time using smoke test containers varies based on your machine specifications.**
49+
50+
- **~7 minutes on an AMD Ryzen 9 7900 with an NVMe drive**
51+
- **~20 minutes using a standard GitHub action runner**
52+
53+
**Notes**
54+
55+
- You may need to set up your Docker hub login to pull images
56+
57+
### Docker Configuration
58+
59+
Create a Docker `daemon.json` file.
60+
61+
```shell
62+
/etc/docker/daemon.json
63+
```
64+
65+
```yaml
66+
{
67+
"default-address-pools" : [
68+
{
69+
"base" : "172.16.0.0/16",
70+
"size" : 24
71+
},
72+
{
73+
"base" : "192.168.0.0/16",
74+
"size" : 24
75+
}
76+
]
77+
}
78+
```
79+
80+
Restart Docker.
81+
82+
### Commands
83+
84+
```shell
85+
git clone https://github.com/prometheus/jmx_exporter
86+
cd jmx_exporter
87+
./integration_test_suite/pull-smoke-test-docker-images.sh
88+
./mvnw clean verify
89+
```
90+
91+
**Notes**
92+
93+
- The `smoke-test.sh` shell script can be used to build and run the integration test suite using smoke test containers.
94+
- `./smoke-test.sh`
95+
- Output is captured and logged to `smoke-test.log`.
96+
97+
### Example Output
98+
99+
```shell
100+
[INFO] ------------------------------------------------------------------------
101+
[INFO] Verifyica 0.7.2 Summary (2024-12-02T13:53:18-05:00)
102+
[INFO] ------------------------------------------------------------------------
103+
[INFO] Test classes : 40 Passed : 40 Failed : 0 Skipped : 0
104+
[INFO] Test arguments : 506 Passed : 506 Failed : 0 Skipped : 0
105+
[INFO] Test methods : 2302 Passed : 2302 Failed : 0 Skipped : 0
106+
[INFO]
107+
[INFO] ------------------------------------------------------------------------
108+
[INFO] TESTS PASSED
109+
[INFO] ------------------------------------------------------------------------
110+
[INFO] Compact Summary | 40 40 0 0 | 506 506 0 0 | 2302 2302 0 0 | 387351.971080 ms | P
111+
[INFO] ------------------------------------------------------------------------
112+
[INFO] Total time : 6 m, 27 s, 351 ms (387351.97108 ms)
113+
[INFO] Finished at : 2024-12-02T13:59:47-05:00
114+
[INFO] ------------------------------------------------------------------------
115+
[INFO] ------------------------------------------------------------------------
116+
[INFO] Reactor Summary for Prometheus JMX Exporter <VERSION>>:
117+
[INFO]
118+
[INFO] Prometheus JMX Exporter ............................ SUCCESS [ 0.755 s]
119+
[INFO] Prometheus JMX Exporter - Collector ................ SUCCESS [ 9.543 s]
120+
[INFO] Prometheus JMX Exporter - Common ................... SUCCESS [ 3.092 s]
121+
[INFO] Prometheus JMX Exporter - Java Agent ............... SUCCESS [ 35.511 s]
122+
[INFO] Prometheus JMX Exporter - Standalone Server ........ SUCCESS [ 5.672 s]
123+
[INFO] Prometheus JMX Exporter - Integration Test Suite ... SUCCESS [ 0.259 s]
124+
[INFO] Prometheus JMX Exporter - JMX Example Application .. SUCCESS [ 1.488 s]
125+
[INFO] Prometheus JMX Exporter - Integration Tests ........ SUCCESS [06:42 min]
126+
[INFO] ------------------------------------------------------------------------
127+
[INFO] BUILD SUCCESS
128+
[INFO] ------------------------------------------------------------------------
129+
[INFO] Total time: 07:39 min
130+
[INFO] Finished at: 2024-12-02T13:59:47-05:00
131+
[INFO] ------------------------------------------------------------------------
132+
```
133+
134+
## Integration Tests (all test containers)
135+
136+
Integration tests use [Verifyica](https://github.com/verifyica-team/verifyica) for integration testing.
137+
138+
Integration tests require Docker configuration changes due to parallel testing/the number of Docker networks used during testing.
139+
140+
**Integration testing using all test containers requires SIGNIFICANT time and disk space.**
141+
142+
- **~100 Docker containers (Java and Prometheus containers)**
143+
- **~2 hours on an AMD Ryzen 9 7900 + NVMe**
144+
- **3+ hours on a Dual Intel Xeon CPU E5-2680 v4**
145+
146+
**Notes**
147+
148+
- You may need to set up your Docker hub login to pull images
149+
150+
### Docker Configuration
151+
152+
Create or edit...
153+
154+
```shell
155+
/etc/docker/daemon.json
156+
```
157+
158+
**Content**
159+
160+
```yaml
161+
{
162+
"default-address-pools" : [
163+
{
164+
"base" : "172.16.0.0/16",
165+
"size" : 24
166+
},
167+
{
168+
"base" : "192.168.0.0/16",
169+
"size" : 24
170+
}
171+
]
172+
}
173+
```
174+
175+
Restart Docker.
176+
177+
### Commands
178+
179+
```shell
180+
git clone https://github.com/prometheus/jmx_exporter
181+
cd jmx_exporter
182+
./integration_test_suite/pull-smoke-test-docker-images.sh
183+
./mvnw clean verify
184+
```
185+
186+
### Scripts
187+
188+
Test scripts are available to build and run various integration test suite scenarios
189+
190+
- [run-quick-test.sh](https://github.com/prometheus/jmx_exporter/blob/main/run-quick-test.sh)
191+
- [run-smoke-test.sh](https://github.com/prometheus/jmx_exporter/blob/main/run-smoke-test.sh)
192+
- [run-regression-test.sh](https://github.com/prometheus/jmx_exporter/blob/main/run-regression-test.sh)
193+
- [run-targeted-test.sh](https://github.com/prometheus/jmx_exporter/blob/main/run-targeted-test.sh)
194+
- [run-stress-test.sh](https://github.com/prometheus/jmx_exporter/blob/main/run-stress-test.sh)
195+
196+
### Output
197+
198+
Output is similar to integration testing using smoke test containers.

‎docs/content/1.2.0/collector.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: "Collector Module"
3+
weight: 6
4+
---
5+
6+
The `collector` module/library is currently published to Maven Central and used as a dependency for some projects.
7+
8+
# Support Statement
9+
10+
The `collector` module/library is designed to serve as an internal project library, and its functionality is specifically tailored for use within the scope of the JMX Exporter.
11+
12+
As such, it is important to note the following:
13+
14+
- This module is intended for internal use within the JMX Exporter.
15+
16+
17+
- It is not _designed_ for consumption as a standalone library or for external integration.
18+
19+
20+
- No Guaranteed API Contract
21+
- The module does not provide API documentation or formal API contracts. The package structure, class names, method names, and method signatures are subject to change without notice, based on evolving project needs.
22+
23+
- Backward Compatibility
24+
- There is no guarantee of backward compatibility. Updates to the module may introduce breaking changes to existing functionality.
25+
26+
### Support Scope
27+
28+
Support for the `collector` module/library is limited outside of the JMX Exporter.
29+
30+
Questions or issues should be addressed to the JMX Exporter maintainers.

‎docs/content/1.2.0/contributing.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: "Contributing"
3+
weight: 5
4+
---
5+
6+
The JMX Exporter uses GitHub to manage issues and reviews of pull requests.
7+
8+
### Trivial Fixes / Improvements
9+
10+
If you have a trivial fix or improvement, go ahead and create a pull request, tagging the maintainers.
11+
12+
- [MAINTAINERS.md](https://github.com/prometheus/jmx_exporter/blob/main/MAINTAINERS.md)
13+
14+
### Advanced Fixes / Improvements
15+
16+
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).
17+
18+
This will avoid unnecessary work and surely give you and us a good deal of inspiration.
19+
20+
### Integration Tests
21+
22+
Integration tests use [Verifyica](https://github.com/verifyica-team/verifyica) for integration testing and are required for code changes.
23+
24+
### Code Formatting
25+
26+
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.
27+
28+
### Branching Strategy
29+
30+
[GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow) is used for branching.
31+
32+
- Pull requests should be opened against `main` for the next release.
33+

‎docs/content/1.2.0/http-mode/_index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: HTTP mode configuration
3+
weight: 3
4+
geekdocCollapseSection: true
5+
---
6+
7+
HTTP mode supports HTTP [authentication](authentication), [SSL](ssl) (HTTPS), as well as HTTP server thread pool [tuning](miscellaneous).

0 commit comments

Comments
 (0)