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

# 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 Tomcat integration with the Chronosphere XDOT Collector to collect Tomcat and
Java Virtual Machine runtime metrics from apps running in your environment.

The Tomcat integration supports Apache Tomcat 9.0 or greater.

## Supported telemetry types

The Tomcat integration supports these telemetry types:

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

## Prerequisites

The 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](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 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 Tomcat integration is enabled by default. To configure the Tomcat integration,
follow these steps:

1. Choose how the 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 more information, see
     [autodiscovery](https://docs.chronosphere.io/ingest/cxdot-collector/autodiscovery).

   Metrics from discovered pods arrive with that pod's Kubernetes metadata attached.
   For more information, see
   [enrichment](https://docs.chronosphere.io/ingest/cxdot-collector/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:

   ```yaml theme={null}
   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.

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:

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

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

### Validate

To validate the Tomcat integration, follow these steps:

1. In the Live Telemetry Analyzer, filter for
   `__name__=cxdot.integration.target.health` and
   `cxdot.integration.name=tomcat`. 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:

   ```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 diagnosing a failing integration, see
[Troubleshooting](https://docs.chronosphere.io/ingest/cxdot-collector/troubleshooting).

## 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 Collector runs the instance.
  If false, the Collector doesn't run it.

* **`endpoints`**
  Type: `array of object`. Optional.
  Static Tomcat 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` 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 TLS for the RMI registry connection. If true, the Collector uses TLS. If false,
  the Collector uses an unencrypted registry connection.

* **`advertised_host_override`**
  Type: `string`. Optional. Default: \`\`.
  Host the Collector uses for Remote Method Invocation (RMI) server connections instead of the
  host advertised by returned RMI stubs. When empty, the Collector uses the registry endpoint
  host.

* **`advertised_port_override`**
  Type: `integer`. Optional. Default: `0`. Minimum: `0`. Maximum: `65535`.
  Port the Collector uses for RMI server connections instead of the port advertised by returned
  RMI stubs. When set to `0`, the 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 Collector collects metrics from each Tomcat JMX endpoint.

* **`bean_detection_interval`**
  Type: `duration`. Optional. Default: `10m`.
  How often the Collector refreshes the set of available JMX beans.

* **`target_system`**
  Type: `string`. Optional. Default: `tomcat`.
  Comma-delimited attribute mapping names to apply. The Tomcat mapping is enabled by default,
  and the 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 Java Management Extensions (JMX) attribute mappings.
  The Collector searches these paths before the embedded Tomcat and Java Virtual Machine (JVM)
  mappings.

* **`tls`**
  Type: `object`. Optional.
  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 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 Collector can use, in preference order. If omitted, the Collector
  uses the secure defaults from the Go TLS library. 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 Collector can use for an elliptic curve Diffie-Hellman ephemeral
  handshake, in preference order. If omitted, the Collector uses the Go TLS library defaults.

* **`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 Collector trusts both sources. If false, the 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 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 Collector can use. If omitted, the Collector uses the maximum
  version supported by the Go TLS library.

* **`tls.min_version`**
  Type: `string`. Optional.
  Minimum TLS protocol version the Collector can use. If omitted, the minimum version is TLS
  1.2.

* **`tls.reload_interval`**
  Type: `duration`. Optional.
  How often the Collector reloads certificate and key files. If omitted, the 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 Collector loads
  the key from the configured device or socket. If false, the 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`.