> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/integrations/sources/tomcat.md).

# Tomcat

The Apache Tomcat source collects metrics from a Tomcat server over JMX and reads its access and catalina log files. Metrics are scraped through the OpenTelemetry JMX metrics gathering jar against an enabled JMX remote endpoint, while logs are read from the configured file paths and optionally parsed into structured fields.

### Supported Telemetry

| Platform | Metrics | Logs | Traces |
| -------- | ------- | ---- | ------ |
| Linux    | ✓       | ✓    |        |
| Windows  | ✓       | ✓    |        |
| macOS    | ✓       | ✓    |        |

### Prerequisites

For metrics, the target Tomcat JVM must have **JMX remote enabled** and reachable from the collector host. Enable it by adding the JMX flags to `CATALINA_OPTS` (typically in `setenv.sh` / `setenv.bat`), for example:

```
-Dcom.sun.management.jmxremote.port=9012
-Dcom.sun.management.jmxremote.rmi.port=9012
-Dcom.sun.management.jmxremote.ssl=false
-Dcom.sun.management.jmxremote.authenticate=false
```

Set `com.sun.management.jmxremote.rmi.port` explicitly so the port is fixed (otherwise the JMX adaptor picks one at random, which breaks firewall configuration). The collector host must be able to reach the configured address and port. See the official [Monitoring and Managing Tomcat](https://tomcat.apache.org/tomcat-10.0-doc/monitoring.html) documentation for details. The collector also requires the OpenTelemetry JMX metrics jar to be installed at the configured jar path.

For logs, Tomcat must be writing the relevant files and the collector must run where it can read those paths (or the files must be shipped to it). Access logging is produced by Tomcat's Access Log Valve, configured in `server.xml`; see the official [Valve Component](https://tomcat.apache.org/tomcat-10.0-doc/config/valve.html) reference. The default paths read by this source are `/usr/local/tomcat/logs/localhost_access_log.*.txt` for access logs and `/usr/local/tomcat/logs/catalina.out` for catalina logs. Adjust them to match your installation.

### Configuration

<figure><img src="/files/VpogE72ADRXaA5cdgcFM" alt="Bindplane docs - Apache Tomcat - image 1"><figcaption></figcaption></figure>

**General**

| Parameter             | Type               | Required | Default               | Description                                                                                                                   |
| --------------------- | ------------------ | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Choose Telemetry Type | Telemetry Selector | No       | `["Logs", "Metrics"]` | Which signals this source collects: Logs, Metrics, or both. Parameters below are relevant only when their signal is selected. |

**Logs**

| Parameter            | Type    | Required | Default                                             | Description                                                          |
| -------------------- | ------- | -------- | --------------------------------------------------- | -------------------------------------------------------------------- |
| Access Logs          | Boolean | No       | `true`                                              | Enable collection of Tomcat access logs.                             |
| Access Log Path(s)   | Strings | Yes      | `/usr/local/tomcat/logs/localhost_access_log.*.txt` | File paths to access logs. Relevant when Access Logs is enabled.     |
| Catalina Logs        | Boolean | No       | `true`                                              | Enable collection of Tomcat catalina logs.                           |
| Catalina Log Path(s) | Strings | Yes      | `/usr/local/tomcat/logs/catalina.out`               | File paths to catalina logs. Relevant when Catalina Logs is enabled. |

**Metrics**

| Parameter | Type    | Required | Default     | Description                                          |
| --------- | ------- | -------- | ----------- | ---------------------------------------------------- |
| Address   | String  | No       | `localhost` | IP address or hostname to scrape for Tomcat metrics. |
| Port      | Integer | No       | `9012`      | Port to scrape for Tomcat metrics.                   |

**Advanced**

| Parameter                       | Type                   | Required | Default                                           | Description                                                                              |
| ------------------------------- | ---------------------- | -------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Parse To                        | Enum: body, attributes | No       | `body`                                            | Parse structured log parts to either body or attributes. Relevant when Logs is selected. |
| Start At                        | Enum: beginning, end   | No       | `end`                                             | Start reading logs from `beginning` or `end`. Relevant when Logs is selected.            |
| Timezone                        | Timezone               | No       | `UTC`                                             | The timezone to use when parsing log timestamps. Relevant when Logs is selected.         |
| Parse                           | Boolean                | No       | `true`                                            | Parses the log fields into structured data. Relevant when Logs is selected.              |
| JMX Metrics Collection Jar Path | String                 | No       | `/opt/opentelemetry-java-contrib-jmx-metrics.jar` | Full path to the JMX metrics jar. Relevant when Metrics is selected.                     |
| Collection Interval             | Integer                | No       | `60`                                              | How often (seconds) to scrape for metrics. Relevant when Metrics is selected.            |

### Examples

#### Collect metrics and logs from a local Tomcat

This source scrapes JMX metrics from a Tomcat server on `localhost:9012` and reads both the access and catalina logs from their default locations.

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  name: tomcat
spec:
  type: tomcat
  parameters:
    - name: telemetry_types
      value: ["Logs", "Metrics"]
    - name: address
      value: localhost
    - name: port
      value: 9012
    - name: enable_access_log
      value: true
    - name: access_log_path
      value:
        - /usr/local/tomcat/logs/localhost_access_log.*.txt
    - name: enable_catalina_log
      value: true
    - name: catalina_log_path
      value:
        - /usr/local/tomcat/logs/catalina.out
```

### Configuration Tips

* The JMX `Port` (default `9012`) must match the `com.sun.management.jmxremote.port` value set in `CATALINA_OPTS`. Set the RMI port to the same value to keep it fixed.
* If JMX authentication or TLS is enabled on Tomcat, configure the JMX gathering jar accordingly; the defaults assume `authenticate=false` and `ssl=false`.
* Use the telemetry-type selector to scope the source: disable Metrics if you only ship logs, or disable Logs (or one of the access/catalina toggles) if you only want metrics.

### Troubleshooting

#### No metrics appear

Symptoms: the source produces no Tomcat metrics.

Solutions:

1. Confirm JMX remote is enabled in `CATALINA_OPTS` and that Tomcat was restarted after the change.
2. Verify the configured Address and Port match the JMX/RMI port and that the collector host can reach it.
3. Confirm the JMX metrics jar exists at the configured jar path.

#### Connection refused

Symptoms: the collector logs a connection error when scraping.

Solutions:

1. Check that the JMX port is listening and not blocked by a firewall.
2. Ensure `com.sun.management.jmxremote.rmi.port` is set so the port stays fixed.

#### No logs appear

Symptoms: access or catalina logs are not collected.

Solutions:

1. Verify the configured log paths exist and that the collector user can read them.
2. Confirm the Access Log Valve is configured in `server.xml` so access logs are being written.
3. If logs are being written but not parsed as expected, check that Parse is enabled and the log format matches.

### Standalone Source

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  name: tomcat
spec:
  type: tomcat
  parameters:
    - name: telemetry_types
      value: ["Logs", "Metrics"]
    - name: address
      value: localhost
    - name: port
      value: 9012
    - name: enable_access_log
      value: true
    - name: access_log_path
      value:
        - /usr/local/tomcat/logs/localhost_access_log.*.txt
    - name: enable_catalina_log
      value: true
    - name: catalina_log_path
      value:
        - /usr/local/tomcat/logs/catalina.out
    - name: collection_interval
      value: 60
```

### Related Resources

* [Apache Tomcat — Monitoring and Managing Tomcat (JMX)](https://tomcat.apache.org/tomcat-10.0-doc/monitoring.html)
* [Apache Tomcat — The Valve Component (Access Log Valve)](https://tomcat.apache.org/tomcat-10.0-doc/config/valve.html)
* [OpenTelemetry JMX Receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/jmxreceiver)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bindplane.com/integrations/sources/tomcat.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.