Metrics Configuration

Metrics are configured in the application configuration file (conf/application.xml) under the <metrics> element:

<application>
    <metrics enabled="true">
        <!-- Layer Configuration -->
        <httpMetrics enabled="true"/>
        <apiMetrics enabled="true"/>
        <serviceMetrics enabled="true"/>
        <threadPoolMetrics enabled="true"/>

        <!-- Event and DLQ metrics can be disabled in cluster mode via th environment settings. -->

        <!-- System Metrics -->
        <jvmMetrics enabled="true"/>
        <systemMetrics enabled="true"/>

        <!-- Application Settings -->
        <application percentilesEnabled="true"
                     maxEndpoints="100"
                     maxUris="500"
                     maxStatusCodes="20"
                     tag="webPDF"
                     logMetricsOnStartup="false"
                     metricCountWarningThreshold="10000">
            <percentiles>
                <percentile>0.5</percentile>
                <percentile>0.95</percentile>
                <percentile>0.99</percentile>
            </percentiles>
        </application>

        <!-- Authentication Configuration -->
        <auth enabled="true"
              username="prometheus"
              password="your-secure-password"/>

        <!-- Registry Configuration -->
        <prometheus enabled="true"/>
        <jmx enabled="true" domain="webpdf.metrics"/>
    </metrics>
</application>

Admin Portal

Currently, the configuration cannot be managed via the Admin Portal in the "Metrics" section.

Configuration Parameters

Global Settings

Attribute	Default	Description
enabled	true	Master switch for the complete metrics subsystem
preset	(none)	Predefined configuration preset: production, development, minimal, or custom

Layer Configuration

Control which metric layers are active via element attributes:

Element	Attribute enabled	Default	Overhead	Description
<httpMetrics>	enabled	true	Medium	HTTP-layer metrics (request duration, size, errors)
<apiMetrics>	enabled	true	Low	REST API-layer metrics (endpoint timing)
<serviceMetrics>	enabled	true	Low	Business logic metrics (web service operations)
<threadPoolMetrics>	enabled	true	Very Low	Thread pool and worker execution metrics

Event and DLQ metrics are enabled by default with the metrics subsystem and can be disabled with the WEBPDF_METRICS_EVENT_PIPELINE_ENABLED Environment Setting.

Overhead Explanation

Overhead indicates the performance impact of metric collection per request:

• Very Low: < 0.05 ms per request (gauges, minimal computation)
• Low: 0.05-0.1 ms per request (simple timers, counters)
• Medium: 0.1-0.2 ms per request (multiple metrics, active tracking)

The HTTP layer has the highest overhead because it executes on every request at the earliest stage and tracks multiple metrics (duration, size, errors, active requests). For performance-critical deployments, consider disabling HTTP metrics while keeping other layers active.

System Metrics

Element	Attribute enabled	Default	Description
<jvmMetrics>	enabled	true	JVM metrics (memory, GC, threads, class loader)
<systemMetrics>	enabled	true	System metrics (CPU, disk space, file descriptors, uptime, Log4j2)

Application Settings

Configured via <application> element and its attributes:

Attribute	Default	Description
percentilesEnabled	true	Enable percentile histogram collection
maxEndpoints	-1 (unlimited)	Maximum unique endpoints to track
maxUris	-1 (unlimited)	Maximum unique URIs to track
maxStatusCodes	-1 (unlimited)	Maximum unique HTTP status codes to track
tag	webPDF	Application tag for all metrics
endpointEnabled	true	Expose the Prometheus-compatible HTTP endpoint
logMetricsOnStartup	false	Log all metrics at startup
metricCountWarningThreshold	10000	Warning threshold for total metric count

Child element <percentiles>:

• Contains multiple <percentile> elements with values between 0.0 and 1.0
• Default percentiles: 0.5, 0.95, 0.99 (if percentilesEnabled="true")

Memory Impact

Percentile histograms consume approximately 1 MB per timer. With default settings, expect 500-1000 MB memory overhead. Consider disabling in memory-constrained environments.

Production Recommendation

Set percentilesEnabled="false" or limit to single percentile, and configure cardinality limits: maxEndpoints="100", maxUris="500", maxStatusCodes="20".

Authentication Configuration

Configured via <auth> element and its attributes:

Attribute	Default	Description
enabled	true	Require authentication for metrics endpoint
username	prometheus	Basic Auth username
password	(none)	Basic Auth password
token	(none)	Bearer Token (alternative to username/password)

See Authentication Guide for detailed authentication configuration.

Registry Configuration

Element	Attribute enabled	Other Attributes	Description
<prometheus>	enabled	-	Enable Prometheus registry for time-series metrics
<jmx>	enabled	domain	Enable JMX registry (default domain: webpdf.metrics)

Configuration Presets

Production Configuration

Optimized for low memory usage:

<metrics enabled="true" preset="production">
    <prometheus enabled="true"/>
</metrics>

Or with explicit settings:

<metrics enabled="true">
    <application percentilesEnabled="false"
                 maxEndpoints="100"
                 maxUris="500"
                 maxStatusCodes="20"/>
    <prometheus enabled="true"/>
</metrics>

Memory overhead: ~150-200 MB

Development Configuration

All features enabled for detailed analysis:

<metrics enabled="true" preset="development">
    <auth enabled="false"/>
    <prometheus enabled="true"/>
</metrics>

Or with explicit settings:

<metrics enabled="true">
    <application percentilesEnabled="true"
                 logMetricsOnStartup="true">
        <percentiles>
            <percentile>0.5</percentile>
            <percentile>0.95</percentile>
            <percentile>0.99</percentile>
        </percentiles>
    </application>
    <auth enabled="false"/>
    <prometheus enabled="true"/>
</metrics>

Memory overhead: ~800-1200 MB

Minimal Configuration

Only essential metrics:

<metrics enabled="true" preset="minimal">
    <prometheus enabled="true"/>
</metrics>

Or with explicit settings:

<metrics enabled="true">
    <httpMetrics enabled="false"/>
    <apiMetrics enabled="false"/>
    <serviceMetrics enabled="true"/>
    <threadPoolMetrics enabled="true"/>
    <jvmMetrics enabled="false"/>
    <systemMetrics enabled="false"/>
    <application percentilesEnabled="false"/>
    <prometheus enabled="true"/>
</metrics>

Memory overhead: ~50-100 MB

Environment Settings

All configuration parameters can also be set via environment variables as an alternative to conf/application.xml:

Core Metrics Settings

XML Element/Attribute	Environment Variable	Type	Description
<metrics enabled="...">	WEBPDF_METRICS_ENABLED	boolean	Master switch for metrics subsystem
<httpMetrics enabled="...">	WEBPDF_METRICS_HTTP_METRICS_ENABLED	boolean	Enable HTTP layer metrics
<apiMetrics enabled="...">	WEBPDF_METRICS_API_METRICS_ENABLED	boolean	Enable API layer metrics
<serviceMetrics enabled="...">	WEBPDF_METRICS_SERVICE_METRICS_ENABLED	boolean	Enable Service layer metrics
<threadPoolMetrics enabled="...">	WEBPDF_METRICS_THREAD_POOL_METRICS_ENABLED	boolean	Enable Thread Pool metrics
Metrics event pipeline setting	WEBPDF_METRICS_EVENT_PIPELINE_ENABLED	boolean	Enable event consumer and DLQ metrics
<jvmMetrics enabled="...">	WEBPDF_METRICS_JVM_METRICS_ENABLED	boolean	Enable JVM metrics
<systemMetrics enabled="...">	WEBPDF_METRICS_SYSTEM_METRICS_ENABLED	boolean	Enable System metrics

Application Settings

XML Element/Attribute	Environment Variable	Type	Description
<application percentilesEnabled="...">	WEBPDF_METRICS_APPLICATION_PERCENTILES_ENABLED	boolean	Enable percentile histogram collection
<application><percentiles>	WEBPDF_METRICS_APPLICATION_PERCENTILES	double[]	Array of percentile values (e.g., [0.5,0.95,0.99])
<application maxEndpoints="...">	WEBPDF_METRICS_APPLICATION_MAX_ENDPOINTS	int	Maximum unique endpoints to track
<application maxUris="...">	WEBPDF_METRICS_APPLICATION_MAX_URIS	int	Maximum unique URIs to track
<application maxStatusCodes="...">	WEBPDF_METRICS_APPLICATION_MAX_STATUS_CODES	int	Maximum unique status codes to track
<application tag="...">	WEBPDF_METRICS_APPLICATION_TAG	String	Application tag for metrics
<application endpointEnabled="...">	WEBPDF_METRICS_APPLICATION_ENDPOINT_ENABLED	boolean	Expose the Prometheus-compatible HTTP endpoint
<application logMetricsOnStartup="...">	WEBPDF_METRICS_LOG_METRICS_ON_STARTUP	boolean	Log metrics configuration at startup
<application metricCountWarningThreshold="...">	WEBPDF_METRICS_APPLICATION_METRIC_COUNT_WARNING_THRESHOLD	int	Warning threshold for metric count

Authentication Configuration

XML Element/Attribute	Environment Variable	Type	Description
<auth enabled="...">	WEBPDF_METRICS_AUTH_ENABLED	boolean	Require authentication for endpoint
<auth username="...">	WEBPDF_METRICS_AUTH_USERNAME	String	Basic Auth username (default: prometheus)
<auth password="...">	WEBPDF_METRICS_AUTH_PASSWORD	String	Basic Auth password
<auth token="...">	WEBPDF_METRICS_AUTH_TOKEN	String	Bearer Token (alternative to username/password)

Registry Configuration

XML Element/Attribute	Environment Variable	Type	Description
<prometheus enabled="...">	WEBPDF_METRICS_PROMETHEUS_ENABLED	boolean	Enable Prometheus registry
<jmx enabled="...">	WEBPDF_METRICS_JMX_ENABLED	boolean	Enable JMX registry
<jmx domain="...">	WEBPDF_METRICS_JMX_DOMAIN	String	JMX domain name

Notation

• Prefix: WEBPDF_METRICS_
• Always UPPERCASE
• Element names are converted: httpMetrics → HTTP_METRICS, apiMetrics → API_METRICS
• Attribute names are converted: percentilesEnabled → PERCENTILES_ENABLED
• CamelCase is converted to SNAKE_CASE
• Dots (.) in configuration paths are replaced by underscores (_)

Example

# Enable metrics and Prometheus registry
export WEBPDF_METRICS_ENABLED=true
export WEBPDF_METRICS_PROMETHEUS_ENABLED=true

# Configure authentication
export WEBPDF_METRICS_AUTH_ENABLED=true
export WEBPDF_METRICS_AUTH_USERNAME=prometheus
export WEBPDF_METRICS_AUTH_PASSWORD=your-secure-password

# Optimize for production (disable percentiles, set limits)
export WEBPDF_METRICS_APPLICATION_PERCENTILES_ENABLED=false
export WEBPDF_METRICS_APPLICATION_MAX_ENDPOINTS=100
export WEBPDF_METRICS_APPLICATION_MAX_URIS=500

# Or enable with custom percentile values (array notation with square brackets)
export WEBPDF_METRICS_APPLICATION_PERCENTILES_ENABLED=true
export WEBPDF_METRICS_APPLICATION_PERCENTILES="[0.95,0.99]"

Priority

If both conf/application.xml and environment variables are provided, environment variables take precedence.

See Also

• Metrics Overview - Main metrics documentation
• Authentication - Configure metrics endpoint authentication
• Metric Reference - Complete list of all metrics
• Integration Guide - Prometheus and Grafana setup