Add Kafka Connect as a built‑in JMX metrics target

[aaaugustine29]

Overview:
This change introduces Kafka Connect as a first‑class JMX target system in the JMX metrics library. It adds a ruleset and documentation that cover both Apache Kafka Connect and Confluent Platform variants from the outset, so users can enable Kafka Connect monitoring without custom YAML.

Details:
Added kafka-connect.yaml JMX rules that map worker, rebalance, connector, task, source/sink task, and task-error MBeans into OpenTelemetry metrics, including Apache‑only metrics (e.g., worker rebalance protocol, per‑connector task counts, predicate/transform metadata, converter metadata, source transaction sizes, sink record lag max).
Defined connector and task status as state metrics using the superset of status values across Apache and Confluent, to avoid vendor‑specific enum mismatches.
Documented the new target in kafka-connect.md, including metric groups, attributes, and the dual‑vendor compatibility model (no renames; Apache list as a superset of Confluent docs).
Added self‑contained tests for the Kafka Connect rules that load the YAML, build metric definitions, and validate key state mappings and metric presence, ensuring the new target is ready to consume from day one.

Testing:
./gradlew -Dorg.gradle.configuration-cache.parallel=false instrumentation:jmx-metrics:library:test

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: aaaugustine29 / name: Aaron Augustine (d20153d, 2f25096, 31b44c8, 471c9a7, 6293d68, 6d3af5f, 7ceb694, 81fa539, 9ccdc08, a2fca88, c08109f, c985e86, d46eb77, dd17633)

[laurit]

@SylvainJuge could you review this

[SylvainJuge]

Hi @aaaugustine29, thanks for opening this!

There are quite a lot of metrics added here, so it makes it quite challenging to review them all.

I don't have any expertise in Kafka Connect, so you are probably more knowledgeable here.

I would suggest to :

• implement test with a real instance of the target system, ideally the two apache/confluent variants
• as a first step, focus on the "essential" metrics, do not include everything that is available, this is where your knowledge might be useful
• try to simplify the the maximum by using metric attributes to provide breakdown when possible if the metrics represent a partition (for example on state).

[SylvainJuge]

This tests mocks the actual kafka connect instance JMX, while this makes testing fast and easier to run without the target kafka connect system, this also means the tests and metrics definitions can easily drift from the actual implementation.

So, the tests here only test the metric mapping is what we expect, not that this mapping actually works as expected on a real kafka connect instance. In order to solve this I would recommend to add a test with a real kafka connect like we have with other systems.

[aaaugustine29]

Ok will do, I was trying to avoid adding too heavy of tests but I'm glad to hear that's acceptable. I'll make sure to get those in there soon! In this case, I'll look into the lightest way to do so and commit.

[aaaugustine29]

@SylvainJuge Thanks for your help and guidance. At this point, the metrics have been reduced to the minimum set without losing any information. That being said, that doesn't mean we need to keep everything. In particular, your previous comment brings up the opportunity for consolidating some of them with metric attributes. However, there will be a loss of info for a niche and advanced group. What's your guidance on this?

And to clarify your comment about testing, having tests that actually instantiate a kafka connect cluster will be very heavy, I could emulate what the apache jmx server would produce, would that be sufficient?

[SylvainJuge]

From the metrics definitions we can assume that connector-startup-attempts-total = connector-startup-failure-total + connector-startup-success-total.
This assumption is confirmed when we look for the probable implementation in https://github.com/apache/kafka/blob/83dc0d7eae2940ea26781276b3dfee5ed65dba15/connect/runtime/src/main/java/org/apache/kafka/connect/runtime/WorkerMetricsGroup.java#L80

From the implementation we know the following:

• the total startup attempt count is incremented when the startup is known to be a failure/success, so after the startup attempt is completed/failed. There is no state where the attempt is "in progress"
• the sum of failure + success will always be equal to the total, thus we don't need an extra metric

This means that we could capture a single kafka.connect.worker.connector.startup metric with a breakdown of the startup result by kafka.connect.worker.connector.startup.result = failure | success

With such a metric, we have the following:

• the total number of startup attempts is provided by discarding the kafka.connect.worker.connector.startup.result attribute and aggregating (sum)
• the total number of startup success/failures is provided by filtering on the value of kafka.connect.worker.connector.startup.result attribute.

Also, we can use yaml anchors to avoid duplication and ensure this is captured in the same metric. The implementation should look like this:

Suggested change

	connector-startup-attempts-total:
	metric: connector.startup.attempts
	type: counter
	unit: "{attempt}"
	desc: The total number of connector startups that this worker has attempted.
	# kafka.connect.worker.connector.startup.failure.total
	connector-startup-failure-total:
	metric: connector.startup.failures
	type: counter
	unit: "{startup}"
	desc: The total number of connector starts that failed.
	# kafka.connect.worker.connector.startup.success.total
	connector-startup-success-total:
	metric: connector.startup.successes
	type: counter
	unit: "{startup}"
	desc: The total number of connector starts that succeeded.
	# kafka.connect.worker.connector.startup
	connector-startup-failure-total:
	metric: &metric connector.startup
	type: &type counter
	unit: &unit "{startup}"
	desc: &desc The total number of connector starts.
	metricAttribute:
	kafka.connect.worker.connector.startup.result: const(failure)
	# kafka.connect.worker.connector.startup.success.total
	connector-startup-success-total:
	metric: *metric
	type: *type
	unit: &unit
	desc: &desc
	metricAttribute:
	kafka.connect.worker.connector.startup.result: const(success)

[SylvainJuge]

We can do the same here with a single kafka.connect.worker.task.startup metric.

[SylvainJuge]

Those metrics have been added about 6 years ago with this PR: https://github.com/apache/kafka/pull/6843/files

A quick look at the implementation seems to indicate that those metrics are produced by iterating over a list of tasks and counting each state. That means the list of states that is expressed here is a complete partition over the all the possible task states.

So here we can replace those 7 metrics with a single kafka.connect.woker.connector.task with a breakdown on kafka.connect.worker.connector.task.state metric attribute.