Apache Tomcat

The Apache Tomcat integration requires CXDOT Collector 1.4.0 or greater. Apache Tomcat is an open source web server for Java apps. Use the Apache Tomcat integration with the CXDOT collector to collect Tomcat and Java Virtual Machine (JVM) runtime metrics from apps running in your environment. The Apache Tomcat integration supports Apache Tomcat 9.0 or greater.

​

Supported telemetry types

The Apache Tomcat integration supports these telemetry types:

​

Prerequisites

The Apache Tomcat integration has the following prerequisites:

• Enable remote Java Management Extensions (JMX) monitoring over Remote Method Invocation (RMI). Configure fixed RMI registry and server ports. For label-based discovery, expose the registry on port 9012. For more information, see Monitoring and Managing Tomcat.
• Make the RMI registry and the RMI server address advertised in returned stubs reachable from the CXDOT collector. Set java.rmi.server.hostname on the Tomcat server, or configure the integration’s advertised host and port overrides when the advertised address isn’t reachable.
• Restrict JMX access to trusted clients and configure authentication and Transport Layer Security (TLS) settings in the integration to match the Tomcat server. For more information, see Tomcat security considerations.

​

Configure

The Apache Tomcat integration is enabled by default. To configure the integration, follow these steps:

1. Choose how the CXDOT collector finds your Tomcat servers:
   • For Tomcat pods with an RMI registry on port 9012, add the app.kubernetes.io/name: tomcat label to the pod template.
   • For Tomcat pods or Services that use another endpoint or require per-target credentials, add autodiscovery annotations for Tomcat. For Services, the cluster Collector that wins leader election scrapes each target once. For more information, see autodiscovery.
   Metrics from discovered pods arrive with that pod’s Kubernetes metadata attached. For more information, see enrichment.
2. Optional: Configure static targets instead of discovered targets, such as Tomcat servers outside your Kubernetes cluster. For example, add the following to the values.yaml for your Helm chart:
   config:
     integrations:
       tomcat:
         endpoints:
           - endpoint: tomcat.example.com:9012
   
   When you configure static targets, this integration instance collects from exactly those targets instead of discovered targets. In Kubernetes cluster mode, the elected cluster Collector scrapes static targets. For more information, see architecture.
3. Optional: Configure a second integration instance to collect from both discovered pods and static targets. For example, add the following to the values.yaml for your Helm chart:
   config:
     integrations:
       tomcat: {}
       tomcat/edge:
         endpoints:
           - endpoint: tomcat.example.com:9012
   
   The tomcat/edge key defines a named instance for the static targets. The bare tomcat key continues to discover targets.
4. Optional: Disable the integration. For example, add the following to the values.yaml for your Helm chart:
   config:
     integrations:
       tomcat:
         enabled: false
   

​

Validate

To validate the Apache Tomcat integration, follow these steps:

1. In Live Telemetry Analyzer, filter for __name__=cxdot.integration.target.health and cxdot.integration.name=tomcat. Confirm that cxdot.integration.target.health reports 1 for each target. The cxdot.integration.target, server.address, and server.port attributes identify the target.
2. In Metrics Explorer, run the following query while the Tomcat servers process requests:
   sum by ("server.address", "server.port") (rate({"tomcat.request.count"}[$__rate_interval]))
   
   Confirm that the query returns the expected time series for each target.

For more information about diagnosing a failing integration, see Troubleshooting. For more information about CXDOT Collector integrations, see CXDOT Collector integrations.

​

Configuration reference

Configure one Apache Tomcat integration instance with the following settings. In Helm values, place these settings under config.integrations.tomcat. In a Collector configuration file, place them under cxdot.integrations.tomcat.

​

Optional settings

• enabled Type: boolean. Optional. Default: true. Whether to enable this Tomcat integration instance. If true, the CXDOT collector runs the instance. If false, the CXDOT collector doesn’t run it.
• endpoints Type: array of object. Optional. Default: []. Static Tomcat Java Management Extensions (JMX) targets. When this list is empty or omitted, the integration uses automatic target discovery. When the list contains targets, this integration instance collects from exactly those targets and doesn’t automatically discover targets. Configure a second named instance to use both methods. Each endpoint can be a host:port Remote Method Invocation (RMI) registry address or a service:jmx:rmi URL.
• endpoints[].endpoint Type: string. Required. Tomcat JMX endpoint as either a host:port RMI registry address or a service:jmx:rmi URL.
• registry_tls Type: boolean. Optional. Default: false. Whether to use Transport Layer Security (TLS) for the RMI registry connection. If true, the CXDOT collector uses TLS. If false, the CXDOT collector uses an unencrypted registry connection.
• advertised_host_override Type: string. Optional. Default: “. Host the CXDOT collector uses for RMI server connections instead of the host advertised by returned RMI stubs. When empty, the CXDOT collector uses the registry endpoint host.
• advertised_port_override Type: integer. Optional. Default: 0. Minimum: 0. Maximum: 65535. Port the CXDOT collector uses for RMI server connections instead of the port advertised by returned RMI stubs. When set to 0, the CXDOT collector uses the advertised port.
• username Type: string. Optional. Username for JMX authentication. Configure username and password together.
• password Type: string. Optional. Password for JMX authentication. Configure username and password together.
• collection_interval Type: duration. Optional. Default: 15s. How often the CXDOT collector collects metrics from each Tomcat JMX endpoint.
• bean_detection_interval Type: duration. Optional. Default: 10m. How often the CXDOT collector refreshes the set of available JMX beans.
• bean_limit Type: integer. Optional. Default: 35000. Minimum: 1. Maximum number of JMX bean matches collected from each endpoint. When the number of matches exceeds this value, the integration drops beans according to the attribute mapping priority.
• target_system Type: string. Optional. Default: tomcat. Comma-delimited attribute mapping names to apply. The Tomcat mapping is enabled by default, and the Java Virtual Machine (JVM) mapping is included automatically. Add -jvm to disable JVM metrics when at least one other mapping is configured.
• attribute_mapping_paths Type: array of string. Optional. Default: []. Directories and files containing custom JMX attribute mappings. The CXDOT collector searches these paths before the embedded Tomcat and JVM mappings.
• tls Type: object. Optional. Default: {}. TLS certificate and client authentication settings for RMI registry and server connections.
• tls.ca_file Type: string. Optional. Path to a PEM-encoded certificate authority (CA) certificate file used to verify the JMX server certificate. If omitted, the CXDOT collector uses the system certificate authority pool.
• tls.ca_pem Type: string. Optional. PEM-encoded certificate authority certificate content used to verify the JMX server certificate.
• tls.cert_file Type: string. Optional. Path to the PEM-encoded client certificate file to present when the JMX server requires mutual TLS authentication.
• tls.cert_pem Type: string. Optional. PEM-encoded client certificate content to present when the JMX server requires mutual TLS authentication.
• tls.cipher_suites Type: array of string. Optional. TLS cipher suites that the CXDOT collector can use, in preference order. If omitted, the CXDOT collector uses secure default cipher suites. For supported names, see https://go.dev/src/crypto/tls/cipher_suites.go.
• tls.curve_preferences Type: array of string. Optional. Elliptic curves that the CXDOT collector can use for an elliptic curve Diffie-Hellman ephemeral handshake, in preference order. If omitted, the CXDOT collector uses its default curves.
• tls.include_system_ca_certs_pool Type: boolean. Optional. Whether to add certificates from the system certificate authority pool to the configured certificate authorities. If true, the CXDOT collector trusts both sources. If false, the CXDOT collector trusts only the configured certificate authorities.
• tls.insecure Type: boolean. Optional. Whether to disable transport security. This setting must be false. Use registry_tls to control transport security for the RMI registry.
• tls.insecure_skip_verify Type: boolean. Optional. Whether to skip verification of the JMX server certificate. If true, the connection is encrypted but isn’t authenticated and is vulnerable to man-in-the-middle attacks. If false, the CXDOT collector verifies the certificate.
• tls.key_file Type: string. Optional. Path to the PEM-encoded client private key file used with cert_file for mutual TLS authentication.
• tls.key_pem Type: string. Optional. PEM-encoded client private key content used with cert_pem for mutual TLS authentication.
• tls.max_version Type: string. Optional. Maximum TLS protocol version the CXDOT collector can use. If omitted, the CXDOT collector uses the highest TLS version it supports.
• tls.min_version Type: string. Optional. Minimum TLS protocol version the CXDOT collector can use. If omitted, the minimum version is TLS 1.2.
• tls.reload_interval Type: duration. Optional. How often the CXDOT collector reloads certificate and key files. If omitted, the CXDOT collector doesn’t reload the files.
• tls.server_name_override Type: string. Optional. Server name to verify in the JMX certificate instead of the endpoint hostname. Use this setting when the certificate name differs from the endpoint hostname.
• tls.tpm Type: object. Optional. Trusted platform module settings for the TLS private key.
• tls.tpm.auth Type: string. Optional. Authorization value for the trusted platform module key.
• tls.tpm.enabled Type: boolean. Optional. Whether to use a trusted platform module for the TLS private key. If true, the CXDOT collector loads the key from the configured device or socket. If false, the CXDOT collector uses the configured key file or in-memory key.
• tls.tpm.owner_auth Type: string. Optional. Owner authorization value for the trusted platform module.
• tls.tpm.path Type: string. Optional. Path to the trusted platform module device or Unix domain socket, such as /dev/tpm0 or /dev/tpmrm0.