> ## Documentation Index
> Fetch the complete documentation index at: https://docs-xcor.paloaltonetworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Apache Tomcat

> Apache Tomcat application and Java Virtual Machine runtime metrics collected over JMX.

The Apache Tomcat integration requires CXDOT Collector 1.4.0 or greater.

[Apache Tomcat](https://tomcat.apache.org/) 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:

| Type | Supported |
| - | - |
| Logs | No |
| Metrics | Yes |
| Traces | No |
| Events | No |

## 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 more
  information, see
  [Monitoring and Managing Tomcat](https://tomcat.apache.org/tomcat-9.0-doc/monitoring.html).
* 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](https://tomcat.apache.org/tomcat-9.0-doc/security-howto.html#JMX).

## Configure

The Apache Tomcat integration is enabled by default. You can configure targets either by
annotating pods in your Kubernetes cluster or by listing static endpoints in your Helm
values. To configure the integration, follow these steps:

1. To collect from Tomcat pods in Kubernetes, add a CXDOT integration annotation to the
   pod template. The annotation key must end with the container name, and its value can
   reference JMX credentials stored in a Kubernetes Secret in the same namespace. For
   example, add the following annotation to your Tomcat workload:

   ```yaml theme={null}
   spec:
     template:
       metadata:
         annotations:
           integrations.cxdot.paloaltonetworks.com/tomcat: |
             schema_version: v1.14
             tomcat:
               endpoints:
                 - endpoint: ${target.host}:${target.port.jmx}
               username: cxdot
               password: ${k8s_secret:tomcat-jmx/password}
       spec:
         containers:
           - name: tomcat
             image: tomcat:10.1
             ports:
               - name: jmx
                 containerPort: 9012
   ```

   The Collector replaces `${target.host}` with the pod IP address,
   `${target.port.jmx}` with the container port named `jmx`, and
   `${k8s_secret:tomcat-jmx/password}` with the `password` key of the `tomcat-jmx`
   Secret. To allow the Collector to read the Secret, add the pod's namespace to
   `apiServer.metadataServer.secretAllowlist` in the Helm values for your CXDOT
   Collector.

   The Collector also discovers Tomcat pods that carry the
   `app.kubernetes.io/name: tomcat` label and expose an RMI registry on port `9012`. A
   CXDOT integration annotation takes precedence over the label for its container. To
   stop collecting from a container, set `tomcat: {enabled: false}` in the annotation.
   Metrics from each discovered pod include that pod's Kubernetes metadata. For more
   information, see
   [autodiscovery](https://docs-xcor.paloaltonetworks.com/ingest/xcor/collector/discover/kubernetes.md).

2. Optional: To collect from Tomcat servers outside your Kubernetes cluster, configure
   static targets. For example, add the following to the
   `values.yaml` for your Helm chart:

   ```yaml theme={null}
   collection:
     cxdot:
       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](https://docs-xcor.paloaltonetworks.com/ingest/xcor/collector/install/kubernetes/architecture.md).

3. Optional: Configure a second integration instance to collect from both annotated
   pods and static targets. For example, add the following to the `values.yaml` for
   your Helm chart:

   ```yaml theme={null}
   collection:
     cxdot:
       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:

   ```yaml theme={null}
   collection:
     cxdot:
       integrations:
         tomcat:
           enabled: false
   ```

### Validate

To validate the Apache Tomcat integration, follow these steps:

1. In [Live Telemetry Analyzer](https://docs-xcor.paloaltonetworks.com/investigate/analyze/telemetry-analyzer.md),
   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](https://docs-xcor.paloaltonetworks.com/investigate/querying/metrics/explorer.md),
   run the following query while the Tomcat servers process requests:

   ```text theme={null}
   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 CXDOT Collector integrations, see the
[integrations catalog](https://docs-xcor.paloaltonetworks.com/ingest/xcor/integrations/collector).

## Configuration reference

Configure one Apache Tomcat integration instance with the following settings. In Helm values,
place these settings under `collection.cxdot.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: `[]`.
  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: empty string.
  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](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`.


## Related topics

- [CXDOT Collector integrations](https://docs-xcor.paloaltonetworks.com/ingest/xcor/integrations/collector.md)
- [Apache](https://docs-xcor.paloaltonetworks.com/ingest/xcor/integrations/collector/apache.md)
- [Apache Mesos](https://docs-xcor.paloaltonetworks.com/ingest/xcor/integrations/collector/mesos.md)
- [Apache Cassandra](https://docs-xcor.paloaltonetworks.com/ingest/xcor/integrations/collector/cassandra.md)
- [Apache Spark](https://docs-xcor.paloaltonetworks.com/ingest/xcor/integrations/collector/spark.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.