docs: document PushGateway shading workaround (#2106) · prometheus/client_java@8ca0eb8 (original) (raw)

Original file line number Diff line number Diff line change
@@ -66,6 +66,12 @@ You can exclude the shaded protobuf classes including the
66 66 `prometheus-metrics-exposition-formats-no-protobuf` module and excluding the
67 67 `prometheus-metrics-exposition-formats` module in your build file.
68 68
69 +If you are using the PushGateway in a shaded jar with `minimizeJar=true`, do not exclude the protobuf classes.
70 +The PushGateway loads the protobuf writer implementation via reflection, so the full
71 +`prometheus-metrics-exposition-formats` artifact must stay on the classpath and the relevant
72 +packages must be preserved during shading. See the [PushGateway docs]({{< relref
73 +"./pushgateway.md" >}}) for the recommended Maven Shade configuration.
74 +
69 75 For example, in Maven:
70 76
71 77 ```xml
Original file line number Diff line number Diff line change
@@ -115,11 +115,43 @@ PushGateway pushGateway = PushGateway.builder()
115 115 However, this requires that the JVM can validate the server certificate.
116 116
117 117 If you want to skip certificate verification, you need to provide your own
118 -[HttpConnectionFactory](/client_java/api/io/prometheus/metrics/exporter/pushgateway/HttpConnectionFactory.html).
118 +`HttpConnectionFactory`. See the
119 +[API docs](/client_java/api/io/prometheus/metrics/exporter/pushgateway/HttpConnectionFactory.html).
119 120 The `PushGatewayTestApp` in `integration-tests/it-pushgateway` has a complete example of this.
120 121
121 122 ## Configuration Properties
122 123
123 124 The [PushGateway](/client_java/api/io/prometheus/metrics/exporter/pushgateway/PushGateway.html)
124 125 supports a couple of properties that can be configured at runtime.
125 126 See [config]({{< relref "../config/config.md" >}}).
127 +
128 +## Troubleshooting shaded jars
129 +
130 +If you build a shaded jar with the Maven Shade Plugin and `minimizeJar=true`, the PushGateway may
131 +fail at runtime with an error like this:
132 +
133 +```text
134 +java.lang.RuntimeException: class
135 +io.prometheus.metrics.expositionformats.PrometheusProtobufWriter is not available
136 +```
137 +
138 +This happens because the PushGateway loads the protobuf writer implementation via reflection. The
139 +Maven Shade Plugin does not detect that reflective usage during minimization, so it may strip the
140 +required classes from the final jar.
141 +
142 +To avoid this, keep the `prometheus-metrics-exposition-formats` artifact on the classpath and
143 +preserve the protobuf-related packages in your shade configuration:
144 +
145 +```xml
146 +<filters>
147 + <filter>
148 + <artifact>io.prometheus:prometheus-metrics-exposition-formats</artifact>
149 + <includes>
150 + <include>io/prometheus/metrics/expositionformats/**</include>
151 + <include>io/prometheus/metrics/shaded/**</include>
152 + </includes>
153 + </filter>
154 +</filters>
155 +```
156 +
157 +Alternatively, disable jar minimization for the shaded build.