[LIVY-1070] Add LivySessionMetrics Codahale gauges for session monitoring
## What changes were proposed in this pull request?
This PR adds server-side session monitoring gauges for LIVY-1070.
Problem: Livy exposes session state via the REST API (/sessions, /batches) but does not publish session counts as Codahale metrics on the existing /metrics endpoint. External monitoring systems must poll the REST API to observe session distribution.
Solution: Introduce LivySessionMetrics, which registers session count gauges into Livy's MetricRegistry at server startup. Gauges are derived from InteractiveSessionManager and BatchSessionManager and exposed alongside existing Livy metrics via the AdminServlet at /metrics.
Metrics registered (18 gauges)
Overall (3)
livy.sessions.total
livy.sessions.active.total
livy.sessions.terminal.total
Interactive (8)
livy.sessions.interactive.total
livy.sessions.interactive.{idle,busy,starting,shutting_down,dead,error,killed}
Batch (7)
livy.sessions.batch.total
livy.sessions.batch.{starting,running,success,dead,error,killed}
Design notes
Additive only — no REST API or session lifecycle behavior changes
Idempotent registration — skips gauge names already present in the registry
Error-safe callbacks — gauge getValue returns 0 on exception
State normalization — handles case and hyphen/underscore variants (e.g. shuttingdown, succeeded)
HA note — gauge values reflect the local Livy server instance; in HA deployments only the leader holds active sessions
Compatibility
No new endpoints; uses existing /metrics AdminServlet
Backward compatible — new gauges appear alongside existing metrics
## How was this patch tested?
Build
mvn package -Pspark3 -Pscala-2.12 -pl server -am \
-s /tmp/livy-mvn-central-settings.xml -DskipTests
Result: BUILD SUCCESS
Unit tests
mvn test -Pspark3 -Pscala-2.12 -pl server \
-s /tmp/livy-mvn-central-settings.xml \
-Dsuites=org.apache.livy.server.LivySessionMetricsSpec
Result: 8/8 tests passed
Test | Coverage -- | -- All 18 gauge registrations | Registration Duplicate registration guard | Idempotency Zero sessions | Empty state Interactive sessions by state | State counting Batch sessions by state (incl. succeeded alias) | State counting Batch succeeded alias | Edge case Overall totals (total, active, terminal) | Aggregation Exception fallback returns 0 | Error handling
Code coverage
JaCoCo agent enabled during test run (server/target/jacoco/main.exec generated).
No UI changes in this PR.
## Was this patch authored or co-authored using generative AI tooling?
Yes, this was co-authored using Cursor to help generate the new test cases.Apache Livy is an open source REST interface for interacting with Apache Spark from anywhere. It supports executing snippets of code or programs in a Spark context that runs locally or in Apache Hadoop YARN.
Pull requests are welcomed! But before you begin, please check out the Contributing section on the Community page of our website.
Guides and documentation on getting started using Livy, example code snippets, and Livy API documentation can be found at livy.apache.org.
To build Livy, you will need:
Debian/Ubuntu:
maven package or maven3 tarball)Redhat/CentOS:
maven package or maven3 tarball)MacOS:
Required python packages for building Livy:
To run Livy, you will also need a Spark installation. You can get Spark releases at https://spark.apache.org/downloads.html.
Livy requires Spark 3.0+. You can switch to a different version of Spark by setting the SPARK_HOME environment variable in the Livy server process, without needing to rebuild Livy.
Livy is built using Apache Maven. To check out and build Livy, run:
git clone https://github.com/apache/livy.git cd livy mvn package
You can also use the provided Dockerfile:
git clone https://github.com/apache/livy.git cd livy docker build -t livy-ci dev/docker/livy-dev-base/ docker run --rm -it -v $(pwd):/workspace -v $HOME/.m2:/root/.m2 livy-ci mvn package -Pspark3 -Pscala-2.12
Note: The
docker runcommand maps the maven repository to your host machine's maven cache so subsequent runs will not need to download dependencies.
By default Livy is built against Apache Spark 3.3.4, but the version of Spark used when running Livy does not need to match the version used to build Livy. Livy internally handles the differences between different Spark versions.
The Livy package itself does not contain a Spark distribution. It will work with any supported version of Spark without needing to rebuild.
| Flag | Purpose |
|---|---|
| -Phadoop2 | Choose Hadoop2 based build dependencies |
| -Pthriftserver | Build and test Livy Thrift Server modules |
| -Pspark3 | Choose Spark 3.x based build dependencies |
| -Pscala-2.12 | Choose Scala 2.12 based build dependencies |