Cleanup documentation (#1076)

* Cleanup of documentation Signed-off-by: dhoard <[email protected]>
prometheus · Dec 2, 2024 · 6ef9985 · 6ef9985
1 parent ecce2c5
commit 6ef9985
Show file tree

Hide file tree

Showing 19 changed files with 371 additions and 91 deletions.
diff --git a/.gitignore b/.gitignore
@@ -12,6 +12,6 @@ target/
 dependency-reduced-pom.xml
 pom.xml.versionsBackup
 integration_test_suite/integration_tests/src/test/resources/common/**.jar
+**/.hugo_build.lock
 smoke-test.log
 regression-test.log
-documentation/src/.hugo_build.lock
diff --git a/docs/content/_index.md b/docs/content/_index.md
@@ -14,6 +14,6 @@ Community provided example YAML configuration files:
 
 - [examples](https://github.com/prometheus/jmx_exporter/tree/main/examples)
 
-Integration tests also provide complex and concrete examples of application and YAML configuration files:
+Integration tests also  provide complex/concrete examples of application and YAML configuration files:
 
 - [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)
diff --git a/docs/content/http-mode/_index.md b/docs/content/http-mode/_index.md
@@ -0,0 +1,6 @@
+---
+title: HTTP mode
+weight: 3
+---
+
+HTTP mode supports HTTP [authentication](authentication), [SSL](ssl) (HTTPS), as well as HTTP server thread pool [tuning](misc).
diff --git a/docs/content/http-mode/authentication.md b/docs/content/http-mode/authentication.md
@@ -0,0 +1,108 @@
+---
+title: Authentication
+weight: 2
+---
+
+HTTP mode supports configuring HTTP BASIC authentication as well as use of a custom authenticator plugin.
+
+## HTTP BASIC Authentication
+
+HTTP BASIC authentication supports using the following configuration algorithms:
+
+- plaintext - plaintext password
+- SHA-1 - SHA-1(`<salt>:<password>`)
+- SHA-256 - SHA-256(`<salt>:<password>`)
+- SHA-512 - SHA-512(`<salt>:<password>`)
+- PBKDF2WithHmacSHA1
+- PBKDF2WithHmacSHA256
+- PBKDF2WithHmacSHA512
+
+---
+
+Plaintext example:
+
+```yaml
+httpServer:
+  authentication:
+    basic:
+      username: Prometheus
+      password: secret
+```
+
+---
+
+SHA-256 example using a salted password SHA-256(`<salt>:<password>`) with a password of `secret`
+
+```yaml
+httpServer:
+  authentication:
+    basic:
+      username: Prometheus
+      passwordHash: 2bf7ed4906ac065bde39f7508d6102a6cdd7153a929ea883ff6cd04442772c99
+      algorithm: SHA-256
+      salt: U9i%=N+m]#i9yvUV:bA/3n4X9JdPXf=n
+```
+
+---
+
+PBKDF2WithHmacSHA256 example with a password of `secret`
+
+```yaml
+httpServer:
+  authentication:
+    basic:
+      username: Prometheus
+      passwordHash: A1:0E:4E:62:F7:1E:0B:59:0A:32:EA:CC:7C:65:37:1F:6D:A6:F1:F1:ED:3F:73:ED:C9:65:19:37:21:5B:6D:4E:9D:C6:61:DF:B5:BF:BB:16:B8:9A:50:14:57:CE:3D:14:67:73:A3:71:1B:87:3B:C4:B1:0E:DC:2D:0B:10:65:D6:F5:B6:DA:07:DD:EE:DA:AC:9C:60:CD:B4:59:0C:C9:CB:A7:3D:7E:30:3E:43:83:E9:E4:13:34:A1:F1:87:5C:24:46:8E:13:90:A6:66:E1:A6:F3:0B:5A:E7:14:8A:98:6A:81:2B:B6:F8:EF:95:D4:82:7E:FB:5E:2D:D3:24:FE:96
+      algorithm: PBKDF2WithHmacSHA256
+      salt: U9i%=N+m]#i9yvUV:bA/3n4X9JdPXf=n
+```
+
+- iterations = `600000` (default value for PBKDF2WithHmacSHA256 )
+- keyLength = `128` bits (default value)
+
+**Notes**
+
+- PBKDF2WithHmacSHA1 default iterations = `1300000`
+- PBKDF2WithHmacSHA256 default iterations = `600000`
+- PBKDF2WithHmacSHA512 default iterations = `210000`
+- default keyLength = `128` (bits)
+
+### Generation of `passwordHash`
+
+- `sha1sum`, `sha256sum`, and `sha512sum` can be used to generate the `passwordHash`
+- `openssl` can be used to generate a PBKDF2WithHmac based algorithm `passwordHash`
+
+# Pluggable Authenticator
+
+It is possible to use a customer pluggable authenticator (`com.sun.net.httpserver.Authenticator`) implementation for the **Java agent**.
+
+The custom pluggable authenticator class needs to be on the jvm classpath.
+
+The class name to load is provided through `authentication/plugin` configuration as follows:
+
+```yaml
+httpServer:
+  authentication:
+    plugin:
+       class: my.custom.AuthenticatorWithNoArgConstructor
+```
+
+If the custom pluggable authenticator needs to provide an authenticated Subject visible to the application, it can set a named attribute on the HttpExchange with that subject.
+
+The agent will arrange that subsequent calls occur in a `Subject.doAs()`.
+
+The name of the attribute must be provided through `subjectAttributeName` configuration as follows:
+
+```yaml
+httpServer:
+  authentication:
+    plugin:
+       class: my.custom.AuthenticatorWithNoArgConstructorThatSetsASubjectAttribute
+       subjectAttributeName: "custom.subject.for.doAs");
+```
+
+#  Complex YAML Configuration Examples
+
+Integration tests  provide complex/concrete examples of application and YAML configuration files.
+
+- [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)
diff --git a/docs/content/http-mode/misc.md b/docs/content/http-mode/misc.md
@@ -0,0 +1,34 @@
+---
+title: Misc
+weight: 4
+---
+
+HTTP mode supports HTTP server thread pool tuning.
+
+**Notes**
+
+- By default, a maximum of 10 threads is used
+
+### Configuration
+
+```yaml
+httpServer:
+  threads:
+    minimum: 1
+    maximum: 10
+    keepAliveTime: 120 # seconds
+```
+
+- `minimum` - minimum number of threads
+- `maximum` - maximum number of threads
+- `keepAliveTime` - thread keep-alive time in seconds
+
+**Notes**
+
+- If the work queue is full, the request will be blocked until space is available in the work queue for the request
+
+#  Complex YAML Configuration Examples
+
+Integration tests  provide complex/concrete examples of application and YAML configuration files.
+
+- [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)
diff --git a/docs/content/rules/rules.md → docs/content/http-mode/rules.md b/docs/content/rules/rules.md → docs/content/http-mode/rules.md
@@ -3,7 +3,7 @@ title: Rules
 weight: 1
 ---
 
-HTTP Mode rules that apply to both the JMX Exporter Java agent and Standalone JMX Exporter.
+HTTP mode rules that apply to both the JMX Exporter Java agent and Standalone JMX Exporter.
 
 Name     | Description
 ---------|------------
@@ -32,7 +32,7 @@ and adjacent underscores are collapsed. There's no limitations on label values o
 A minimal config is `{}`, which will connect to the local JVM and collect everything in the default format.
 Note that the scraper always processes all mBeans, even if they're not exported.
 
-**NOTES**
+ **Notes**
 
 Both `whitelistObjectNames` and `blacklistObjectNames` are still supported for backward compatibility, but should be considered deprecated.
 
@@ -61,8 +61,8 @@ domain_beanPropertyValue1_key1_key2_...keyN_attrName{beanpropertyName2="beanProp
 ```
 If a given part isn't set, it'll be excluded.
 
-# Examples
+#  Complex YAML Configuration Examples
 
-The integration tests provide various configuration examples.
+Integration tests  provide complex/concrete examples of application and YAML configuration files.
 
-[/integration_test_suite/integration_tests/src/test/resources/io/prometheus/jmx/test](/integration_test_suite/integration_tests/src/test/resources/io/prometheus/jmx/test)
+- [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)
diff --git a/docs/content/http-mode/ssl.md b/docs/content/http-mode/ssl.md
@@ -0,0 +1,54 @@
+---
+title: SSL
+weight: 3
+---
+
+HTTP mode supports configuring SSL (HTTPS) access using either a JKS or PKCS12 format keystore.
+
+**Notes**
+
+- Keystore type is dependent on the Java version
+- Exporter YAML configuration overrides System properties
+
+### Configuration (using Exporter YAML)
+
+1. Add configuration to your exporter YAML file
+
+```yaml
+httpServer:
+  ssl:
+    keyStore:
+      filename: localhost.jks
+      password: changeit
+    certificate:
+      alias: localhost
+```
+
+2. Create a keystore and add your certificate
+
+### Configuration (using System properties)
+
+1. Add configuration to your exporter YAML file
+
+```yaml
+httpServer:
+  ssl:
+    certificate:
+      alias: localhost
+```
+
+2. Add your certificate to the application's Java keystore
+
+The exporter YAML file `alias` should match the certificate alias of the certificate you want to use for the HTTPS server.
+
+3. Define the application system properties for the Java keystore
+
+```shell
+-Djavax.net.ssl.keyStore=<keystore file> -Djavax.net.ssl.keyStorePassword=<keystore password>
+```
+
+#  Complex YAML Configuration Examples
+
+Integration tests  provide complex/concrete examples of application and YAML configuration files.
+
+- [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)
diff --git a/docs/content/java-agent/_index.md b/docs/content/java-agent/_index.md
@@ -2,3 +2,19 @@
 title: Java Agent
 weight: 1
 ---
+
+The JMX Exporter Java agent jar 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.**
+
+# Jar File
+
+The JMX Exporter Java agent is packaged in `jmx_prometheus_javaagent-<VERSION>.jar`
+
+# Installation
+
+Installation depends on which modes you want to support:
+
+- [HTTP mode](/java-agent/http-mode/)
+- [OpenTelemetry mode](/java-agent/opentelemetry-mode/)
+- [Combined mode](/java-agent/combined-mode/)
diff --git a/docs/content/java-agent/combined-mode.md b/docs/content/java-agent/combined-mode.md
@@ -1,24 +1,28 @@
 ---
-title: Combined Mode
+title: Combined mode
 weight: 4
 ---
 
-Combined Mode allows for both HTTP Mode and OpenTelemetry mode metrics collections methods.
+Combined mode allows for both HTTP mode and OpenTelemetry mode metrics collection methods.
 
-### HTTP Mode
+### HTTP mode
 
 Exposes metric using an HTTP endpoint.
 
 - metrics are collected when the HTTP endpoint is accessed
 - "pull" model
 
-### OpenTelemtry Mode
+### OpenTelemetry mode
 
 Pushes metrics to an OpenTelemetry endpoint.
 
 - metrics are periodically collected and pushed OpenTelemetry endpoint
 - "push" model
 
+**Notes**
+
+-  Due to the indepenent collection methods, HTTP mode metrics most likely  will not match OpenTelemetry mode metrics exactly
+
 # Installation
 
 ### Example
@@ -27,11 +31,11 @@ Pushes metrics to an OpenTelemetry endpoint.
 java -javaagent:jmx_prometheus_javaagent-<VERSION>.jar=[HOSTNAME:]<PORT>:<EXPORTER.YAML> -jar <YOUR_APPLICATION.JAR>
 ```
 
-**NOTES**
+ **Notes**
 
 - `<PORT>` is required
 - `[HOSTNAME]` is optional
-  - if provided, must be separated from `<PORT>` using a colon (`:`) (e.g., `myserver:12345`)
+  - if provided, must be separated from `<PORT>` using a colon (`:`) (e.g., `server:12345`)
 
 ### Concrete Example
 
@@ -54,12 +58,12 @@ rules:
 
 # Advanced YAML Configuration
 
-Reference HTTP Mode [Rules](/rules/rules/) for various `exporter.yaml` metrics configuration options.
+Reference HTTP mode [Rules](/http-mode/rules/) for various `exporter.yaml` metrics configuration options.
 
 # Metrics
 
 1. Run your application.
-2. Access HTTP Mode metrics using a browser to view your metrics.
+2. Access HTTP mode metrics using a browser to view your metrics.
 
 ```
 http://<APPLICATION_HOSTNAME_OR_IP>:<PORT>/metrics
@@ -72,4 +76,10 @@ my_count_total{status="error"} 1.0
 my_count_total{status="ok"} 2.0
 ```
 
-3. Access your OpenTelemetry platform to view OpenTelemetry metrics.
+3. Access your OpenTelemetry platform to view OpenTelemetry metrics.
+
+#  Complex YAML Configuration Examples
+
+ Integration tests  provide complex/concrete examples of application and YAML configuration files.
+
+- [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)
diff --git a/docs/content/java-agent/general-information.md b/docs/content/java-agent/general-information.md