PXF monitoring

Anton Monakov

Contents

View PXF status from the command line
PXF service runtime monitoring
Examine PXF metrics
Filter metric data

You can monitor the PXF status from the command line and via several HTTP endpoints exposed by PXF. These endpoints provide additional information about the PXF service runtime status, and you can use them to query the health, build information, and various metrics of the running process.

The pxf cluster status command displays the status of the PXF service instance on all Greengage DB cluster hosts. The pxf status command displays the status of the PXF service instance on the local Greengage DB host. Only the gpadmin user can request the status of the PXF service. For the full description of the pxf and pxf cluster commands, see Overview of the pxf commands and Overview of the pxf cluster commands.

To view the PXF status in a Greengage DB cluster:

On the Greengage DB master host, log in as gpadmin.
Run the pxf cluster status command:

$ pxf cluster status

The output should look similar to the following:

Checking status of PXF servers on coordinator host,
standby coordinator host, and 2 segment hosts...
PXF is running on 4 out of 4 hosts

PXF exposes the following HTTP endpoints that let you monitor a PXF service running on the local host:

/actuator/health — returns the status of the PXF service.
/actuator/info — returns build information for the PXF service.
/actuator/metrics — returns JVM, extended Tomcat, system, process, Log4j2, and PXF-specific metrics for the PXF service.
/actuator/prometheus — returns all metrics in a format that can be further processed by a Prometheus server.

The HTTP endpoints and the monitoring information returned by PXF are available to any user.

You can view the data associated with a specific endpoint by using the following URL (either opening it in a browser or running the curl command):

http://localhost:5888/<endpoint>[/<name>]

NOTE

For the alternative deployment topology for PXF, the URL looks as follows:

http://<pxf_listen_address>:<port>/<endpoint>[/<name>]

To learn more about PXF deployment topologies, see Installation.

For example, to view the build information for the PXF service running on a local host from the command line, query the /actuator/info endpoint:

$ curl http://localhost:5888/actuator/info

The output should look similar to the following:

{"build":{"pxfApiVersion":"16","version":"6.15.0","artifact":"pxf-service","name":"pxf-service","time":"2025-09-26T12:13:51.925Z","group":"org.greenplum.pxf"}}

To view the status of the PXF service running on the local Greengage DB host from the command line, query the /actuator/health endpoint:

$ curl http://localhost:5888/actuator/health

The output should look similar to the following:

{"status":"UP","groups":["liveness","readiness"]}

Because the PXF service is built on Spring Boot, it exposes the JVM, extended Tomcat, and system metrics. See Metrics in the Spring Boot documentation for more information about these metrics.

The information returned when you query a metric is the aggregate data collected since the last start of the PXF service. To view the list of all available PXF service metrics, query the /metrics endpoint:

$ curl http://localhost:5888/actuator/metrics

PXF also exposes the following specific metrics.

Metric name	Description
pxf.executor.active	The number of threads that are actively executing tasks. Since the states of tasks and threads may change dynamically during computation, the returned value is approximate
pxf.executor.completed	The total number of executed tasks. Since the states of tasks may change dynamically during computation, the returned value is approximate but does not decrease across successive calls
pxf.executor.pool.core	The core number of threads for the pool
pxf.executor.pool.max	The maximum allowed number of threads in the pool
pxf.executor.pool.size	The current number of threads in the pool
pxf.executor.queue.capacity	The maximum number of tasks to be added to the queue
pxf.executor.queue.remaining	The number of additional tasks that the queue can accept without blocking
pxf.executor.queued	The number of tasks that are queued for execution. Since the states of tasks may change dynamically during computation, the returned value is approximate

Metric name

Description

pxf.executor.active

The number of threads that are actively executing tasks. Since the states of tasks and threads may change dynamically during computation, the returned value is approximate

pxf.executor.completed

The total number of executed tasks. Since the states of tasks may change dynamically during computation, the returned value is approximate but does not decrease across successive calls

pxf.executor.pool.core

The core number of threads for the pool

pxf.executor.pool.max

The maximum allowed number of threads in the pool

pxf.executor.pool.size

The current number of threads in the pool

pxf.executor.queue.capacity

The maximum number of tasks to be added to the queue

pxf.executor.queue.remaining

The number of additional tasks that the queue can accept without blocking

pxf.executor.queued

The number of tasks that are queued for execution. Since the states of tasks may change dynamically during computation, the returned value is approximate

In addition, the following metrics related to data transfer are available. Note however that since the PXF service processes running on the master and standby master hosts are not involved in data transfer, these metrics can only be examined when requested from a segment host.

Metric name	Description
pxf.fragments.sent	The number of fragments and the total time it took to send all fragments to Greengage DB
pxf.records.sent	The number of records that PXF sent to Greengage DB
pxf.records.received	The number of records that PXF received from Greengage DB
pxf.bytes.sent	The number of bytes that PXF sent to Greengage DB
pxf.bytes.received	The number of bytes that PXF received from Greengage DB
http.server.requests	Standard metric augmented with PXF tags

Metric name

Description

pxf.fragments.sent

The number of fragments and the total time it took to send all fragments to Greengage DB

pxf.records.sent

The number of records that PXF sent to Greengage DB

pxf.records.received

The number of records that PXF received from Greengage DB

pxf.bytes.sent

The number of bytes that PXF sent to Greengage DB

pxf.bytes.received

The number of bytes that PXF received from Greengage DB

http.server.requests

Standard metric augmented with PXF tags

All returned metrics are tagged with the application label; the value of this tag is always pxf-service.

PXF-specific metrics are tagged with the additional labels: user, segment, profile, and server. All of these tags are present for each PXF metric. PXF returns the unknown tag value when the value cannot be determined.

You can use the tags to filter the information returned for PXF-specific metrics. For example, to examine the pxf.bytes.sent metric for the PXF server named oracle located on segment 2 on the local host, run the following command:

$ curl http://localhost:5888/actuator/metrics/pxf.bytes.sent?tag=segment:2&tag=server:oracle

The output should look similar to the following:

{"name":"pxf.bytes.sent","measurements":[{"statistic":"COUNT","value":272.0}],"availableTags":[{"tag":"server","values":["oracle"]},{"tag":"application","values":["pxf-service"]},{"tag":"profile","values":["jdbc"]},{"tag":"user","values":["gpadmin"]}]}

Certain metrics, such as pxf.fragments.sent, include an additional tag named outcome; you can examine its value (success or error) to determine if all data for the fragment was sent. You can also use this tag to filter the aggregated data.

Grant user access to PXF

PXF configuration files

PXF monitoring

View PXF status from the command line

PXF service runtime monitoring

Examine PXF metrics

Filter metric data