Skip to content

Commit 66dcb40

Browse files
author
Cary Huang
committed
updates
1 parent ddffe91 commit 66dcb40

File tree

9 files changed

+398
-0
lines changed

9 files changed

+398
-0
lines changed

‎docs/en/monitoring/jmx_monitor.md

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
# JMX MBEAN Monitoring
2+
3+
## JMX (Java Management Extensions)
4+
JMX, or Java Management Extensions, is a Java technology that provides tools for managing and monitoring applications, system objects, devices, and service-oriented networks. It allows developers to expose application information and enables external tools to access and interact with this information for monitoring and management purposes.
5+
6+
## JMX MBean for Debezium
7+
Debezium connectors expose metrics via the MBean name for the connector with MBean tag equals to the connector name. These metrics, which are specific to each connector instance, provide data about the behavior of the connector’s snapshot, streaming, and schema history processes.
8+
9+
## Enable JMX on a Connector with synchdb_add_jmx_conninfo() or disable with synchdb_del_jmx_conninfo()
10+
The synchdb_add_jmx_conninfo() function adds JMX monitoring configuration to an existing connector. This enables runtime monitoring and diagnostics via tools like JConsole or Prometheus JMX Exporter.
11+
12+
**Function Signature**
13+
synchdb_add_jmx_conninfo(
14+
name text,
15+
jmx_listenaddr text,
16+
jmx_port integer,
17+
jmx_rmiserveraddr text,
18+
jmx_rmiport integer,
19+
jmx_auth boolean,
20+
jmx_auth_passwdfile text,
21+
jmx_auth_accessfile text,
22+
jmx_ssl boolean,
23+
jmx_ssl_keystore text,
24+
jmx_ssl_keystore_pass text,
25+
jmx_ssl_truststore text,
26+
jmx_ssl_truststore_pass text
27+
)
28+
29+
synchdb_del_jmx_conninfo(
30+
name text
31+
)
32+
33+
34+
| Parameter | Description |
35+
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
36+
| **`name`** | *(text)*<br>The name of the existing connector to which JMX configuration should be added. Must already exist in `synchdb_conninfo`. |
37+
| **`jmx_listenaddr`** | *(text)*<br>The IP address on which the JVM will listen for JMX connections. Use `'0.0.0.0'` to listen on all network interfaces, or specify a specific IP. |
38+
| **`jmx_port`** | *(integer)*<br>The local port for JMX communication (used for client discovery). Must be open and not in use. |
39+
| **`jmx_rmiserveraddr`** | *(text)*<br>The public/external IP address used by remote JMX clients (e.g., JConsole) to connect to the JVM. Usually set to the host machine’s external IP. |
40+
| **`jmx_rmiport`** | *(integer)*<br>The RMI server port used for actual JMX object communication. This must also be open in firewall and network settings. Usually the same as `jmx_port`. |
41+
| **`jmx_auth`** | *(boolean)*<br>Enable authentication for JMX? If `true`, clients must provide a username/password stored in the files below. |
42+
| **`jmx_auth_passwdfile`** | *(text)*<br>Path to the password file used for JMX authentication. If not using authentication, pass `'null'`. |
43+
| **`jmx_auth_accessfile`** | *(text)*<br>Path to the access control file defining roles (e.g., `monitor`, `control`). Required only if authentication is enabled. If not using authentication, pass `'null'` |
44+
| **`jmx_ssl`** | *(boolean)*<br>Enable SSL encryption for JMX connections? Set to `true` to secure communication. |
45+
| **`jmx_ssl_keystore`** | *(text)*<br>Path to the keystore file (in JKS format) containing the server’s private key and certificate. Required if `jmx_ssl = true`. |
46+
| **`jmx_ssl_keystore_pass`** | *(text)*<br>Password for the keystore file. |
47+
| **`jmx_ssl_truststore`** | *(text)*<br>Path to the truststore (JKS) that holds trusted CA certificates. Used to verify client identities if mutual TLS is configured. |
48+
| **`jmx_ssl_truststore_pass`** | *(text)*<br>Password for the truststore file. |
49+
50+
### Password and Access Files for JMX Authentication
51+
When enabling JMX authentication in your JVM configuration (i.e., setting jmx_auth = true), you must provide two files:
52+
53+
Password File – defines usernames and their passwords.
54+
55+
Access File – defines access levels for those users.
56+
57+
These files are used by the JVM to control who can connect and what they are allowed to do.
58+
59+
**Password File**:
60+
61+
This file stores valid JMX usernames and their corresponding passwords.
62+
63+
Format:
64+
```
65+
# Format: username password
66+
<username> <password>
67+
68+
```
69+
70+
Example:
71+
72+
```
73+
monitorRole mySecretPassword
74+
controlRole anotherSecretPassword
75+
76+
```
77+
78+
monitorRole and controlRole are example usernames. Replace mySecretPassword and anotherSecretPassword with strong passwords of your choice. You can define multiple users.
79+
80+
**Access File**:
81+
82+
This file defines what each user is allowed to do via JMX. Possible access levels:
83+
84+
* readonly – can view MBeans but not modify them.
85+
* readwrite – can both view and modify MBeans.
86+
87+
Format:
88+
```
89+
# Format: username access_level
90+
<username> <access>
91+
92+
```
93+
94+
Example:
95+
```
96+
monitorRole readonly
97+
controlRole readwrite
98+
99+
```
100+
**File Permissions**:
101+
Make sure both files are owned by the user running the JVM, and have restricted permissions:
102+
103+
```
104+
chmod 600 jmxpwd.file jmxacc.file
105+
chown youruser:youruser jmxpwd.file jmxacc.file
106+
107+
```
108+
109+
## synchdb_add_jmx_conninfo Examples
110+
111+
**Enable JMX MBean with no authentication and no SSL:**
112+
113+
```sql
114+
SELECT synchdb_add_jmx_conninfo(
115+
'mysqlconn', -- existing connector name
116+
'0.0.0.0', -- JMX listen address
117+
9010, -- JMX listen port
118+
'10.55.13.17', -- JMX RMI server address - for remote client connect
119+
9010, -- JMX RMI server port - for remoet client connect
120+
false, -- use authentication?
121+
'null', -- password file for authentication
122+
'null', -- access file for authentication
123+
false, -- use SSL?
124+
'null', -- SSL keystore path
125+
'null', -- SSL keystore password
126+
'null', -- SSL trust store
127+
'null'); -- SSL trust store password
128+
```
129+
130+
**Enable JMX MBean with authentication**
131+
132+
```sql
133+
SELECT synchdb_add_jmx_conninfo(
134+
'mysqlconn', -- existing connector name
135+
'0.0.0.0', -- JMX listen address
136+
9010, -- JMX listen port
137+
'10.55.13.17', -- JMX RMI server address - for remote client connect
138+
9010, -- JMX RMI server port - for remoet client connect
139+
true, -- use authentication?
140+
'/path/to/passwd.file', -- password file for authentication
141+
'/path/to/access.file', -- access file for authentication
142+
false, -- use SSL?
143+
'null', -- SSL keystore path
144+
'null', -- SSL keystore password
145+
'null', -- SSL trust store
146+
'null'); -- SSL trust store password
147+
```
148+
149+
**Enable JMX MBean with authentication and SSL without SSL client verify**
150+
151+
```sql
152+
SELECT synchdb_add_jmx_conninfo(
153+
'mysqlconn', -- existing connector name
154+
'0.0.0.0', -- JMX listen address
155+
9010, -- JMX listen port
156+
'10.55.13.17', -- JMX RMI server address - for remote client connect
157+
9010, -- JMX RMI server port - for remoet client connect
158+
true, -- use authentication?
159+
'/path/to/passwd.file', -- password file for authentication
160+
'/path/to/access.file', -- access file for authentication
161+
true, -- use SSL?
162+
'/path/to/keystore', -- SSL keystore path
163+
'keystorepass', -- SSL keystore password
164+
'null', -- SSL trust store
165+
'null'); -- SSL trust store password
166+
```
167+
168+
**Enable JMX MBean with authentication and SSL + SSL client verify**
169+
170+
```sql
171+
SELECT synchdb_add_jmx_conninfo(
172+
'mysqlconn', -- existing connector name
173+
'0.0.0.0', -- JMX listen address
174+
9010, -- JMX listen port
175+
'10.55.13.17', -- JMX RMI server address - for remote client connect
176+
9010, -- JMX RMI server port - for remoet client connect
177+
true, -- use authentication?
178+
'/path/to/passwd.file', -- password file for authentication
179+
'/path/to/access.file', -- access file for authentication
180+
true, -- use SSL?
181+
'/path/to/keystore', -- SSL keystore path
182+
'keystorepass', -- SSL keystore password
183+
'/path/to/truststore', -- SSL trust store
184+
'truststorepass'); -- SSL trust store password
185+
```
186+
187+
## Visualize JMX metrics with jconsole
188+
When a connector with JMX configuration is started, the JMX service will be running on the designated port number. We can use `jconsole` that comes with Java distribution to connect to JMX server. It is possible to connect locally via the JVM (connector worker) PID or via IP address and port number. If authentication is enabled, username and password are required as well. If no authentication is used, these can be left empty.
189+
190+
![img](/images/jmx.jpg)
191+
192+
193+
Once connected, we can view all the details about JVM's operating metrics such as CPU, memory, class utilization, threads...etc.
194+
195+
![img](/images/jmx2.jpg)
196+
![img](/images/jmx3.jpg)
197+
![img](/images/jmx4.jpg)
198+
199+
## Visualize Debezium JMX MBeans
200+
201+
The last tab is MBeans, which contains the Debezium specific metrics for schema history, snapshot and streaming stages.
202+
203+
![img](/images/jmx5.jpg)
204+
![img](/images/jmx6.jpg)
205+
![img](/images/jmx7.jpg)
206+
207+
Based on the connector type, the MBean metrics may be different. Refer to Debezium connector documentation on the list of metrics captured:
208+
209+
* [MBeans for MySQL](https://debezium.io/documentation/reference/stable/connectors/mysql.html#mysql-snapshot-metrics)
210+
* [MBeans for SQL Server](https://debezium.io/documentation/reference/stable/connectors/sqlserver.html#sqlserver-snapshot-metrics)
211+
* [MBeans for Oracle](https://debezium.io/documentation/reference/stable/connectors/oracle.html#oracle-snapshot-metrics)

‎docs/images/jmx.jpg

54.5 KB
Loading

‎docs/images/jmx2.jpg

117 KB
Loading

‎docs/images/jmx3.jpg

110 KB
Loading

‎docs/images/jmx4.jpg

216 KB
Loading

‎docs/images/jmx5.jpg

128 KB
Loading

‎docs/images/jmx6.jpg

182 KB
Loading

‎docs/images/jmx7.jpg

177 KB
Loading

0 commit comments

Comments
 (0)