The Greenplum Streaming Server (GPSS) manages communication and data transfer between a client (for example, the Tanzu Greenplum Connector for Informatica) and Greenplum Database. You must configure and start a GPSS instance before you use the service to load data into Greenplum Database.


The Greenplum Streaming Server gpss and gpsscli command line utilities are automatically installed with Greenplum Database version 5.16 and later.

Before you start a GPSS server instance, ensure that you:

  • Install and start a compatible Greenplum Database version.
  • Can identify the hostname of your master node.
  • Can identify the port on which your Greenplum Database master server process is running, if it is not running on the default port (5432).
  • Select one or more GPSS host machines that have connectivity to:
    • The GPSS client host systems.
    • The Greenplum Database master and all segment hosts.

If you are using the gpsscli client utility, ensure that you run the command on a host that has connectivity to:

  • The client data source host systems. For example, for a Kafka data source, you must have connectivity to each broker host in the Kafka cluster.
  • The Greenplum Database master and all segment hosts.

Registering the GPSS Extension

The Greenplum Database and the Greenplum Streaming Server download packages install the GPSS extension. This extension must be registered in each database in which Greenplum users use GPSS to write data to Greenplum tables.

GPSS automatically registers its extension in a database the first time a Greenplum superuser or the database owner initiates a load job. You must manually register the extension in a database if non-privileged Greenplum users will be the first or only users of GPSS in that database.

Perform the following procedure as a Greenplum Database superuser or the database owner to manually register the GPSS extension:

  1. Open a new terminal window, log in to the Greenplum Database master host as the gpadmin administrative user, and set up the Greenplum environment. For example:

    $ ssh gpadmin@gpmaster
    gpadmin@gpmaster$ . /usr/local/greenplum-db/
  2. Start the psql subsystem, connecting to a database in which you want to register the GPSS formatter function. For example:

    gpmaster$ psql -d testdb
  3. Enter the following command to register the extension:

    testdb=# CREATE EXTENSION gpss;
  4. Perform steps 2 and 3 for each database in which the Greenplum Streaming Server will write client data.

Configuring the Greenplum Streaming Server

You configure an invocation of the Greenplum Streaming Server via a JSON-formatted configuration file. This configuration file includes properties that identify the listen address of the GPSS service and an optional debug server port number, as well as the gpfdist service host, bind address, and port number. You can specify encryption options in the file, can configure a password shadow encode/decode key, and can also configure whether GPSS reuses external tables.

The contents of a sample GPSS JSON configuration file named gpsscfg1.json follow:

    "ListenAddress": {
        "Host": "",
        "Port": 5019
        "DebugPort": 9998
    "Gpfdist": {
        "Host": "",
        "Port": 8319,
        "ReuseTables": false
    "Shadow": {
        "Key": "a_very_secret_key"

Refer to the gpss.json reference page for detailed information about the GPSS configuration file format and the configuration properties that the utility supports.

Note: If your Kafka or Greenplum Database clusters are using Kerberos authentication or SSL encryption, see Configuring the Streaming Server for Encryption and Authentication.

Note: Refer to Configuring the Streaming Server for Client-to-Server Authentication for information about configuring client authentication for GPSS.

Running the Greenplum Streaming Server

You use the gpss utility to start an instance of the Greenplum Streaming Server on the local host. When you run the command, you provide the name of the configuration file that defines the properties of the GPSS and gpfdist service instances. You can also specify the name of a directory to which gpss writes server and progress log files. For example, to start a GPSS instance specifying a log directory named gpsslogs relative to the current working directory:

$ gpss --config gpsscfg1.json --log-dir ./gpsslogs

By default, GPSS waits 10 seconds to establish a connection to Greenplum Database. If GPSS does not establish the connection in that time, a time out error is displayed and the gpss command returns. You can change the time out value by setting the GPDB_CONNECT_TIMEOUT environment variable before or when you start GPSS. For example, to set the timeout to 30 seconds, start the GPSS instance as follows:

$ GPDB_CONNECT_TIMEOUT=30 gpss --config gpsscfg1.json --log-dir ./gpsslogs

The default mode of operation for gpss is to wait for, and then consume, job requests and data from a client. When run in this mode, gpss waits indefinitely. You can interrupt and exit the command with Control-c. You may also choose to run gpss in the background (&). In both cases, gpss writes server log and status messages to stdout.

Note: gpss keeps track of the status of each client job in memory. When you stop a GPSS server instance that did not specify a JobStore setting in its server configuration file, you lose all registered jobs. You must re-submit any previously-submitted jobs that you require after you restart the server instance. gpss will resume a job from the last load offset.

Refer to the gpss reference page for additional information about this command.

About GPSS Logging

The gpss, gpsscli, and gpkafka commands each write log messages to stdout (front-end) and to a log file (back-end). These messages provide useful information about GPSS command processing and any errors that it encounters.

GPSS supports the following log levels, listed in order from most to least severe:

Level Description
fatal Logs conditions that prevent GPSS from functioning, such as being unable to listen on the configured port.
error Logs job failure messages.
warn or warning Logs messages that contain information that requires the user's attention, such as the use of deprecated features or notification of job retry in progress.
info Logs messages that contain information about GPSS actions, including job status changes and requests between the GPSS client and server.
debug Logs more detailed and more verbose messages that may aid in troubleshooting.

The default log level for command front-end messages to stdout is info. The default log level for back-end messages that the commands write to the log file is debug.

You can change the front-end or back-end log level by specifying a Logging block in the gpss.json GPSS server configuration file and setting the appropriate property:

"Logging": {
    "Backendlevel": "<level>",
    "Frontendlevel": "<level>"

The default format for command front-end messages that GPSS writes to stdout uses spaces between fields. You can provide options to commands to instruct GPSS to write the front-end messages in CSV format, or to use color in the message. The default format for back-end messages that GPSS writes to the log file is CSV format.

Managing GPSS Log Files

If you specify the -l or --log-dir option when you start gpss or run a gpsscli subcommand, GPSS writes log messages to a file in the directory that you specify. If you do not provide this option, GPSS writes log messages to a file in the $HOME/gpAdminLogs directory.

GPSS writes server log messages to a file with the following naming format, where date identifies the date that the log file was created. This date reflects the date that you started the gpss server instance, or the date that the log was rotated for that server instance (see Rotating the GPSS Server Log File below):


GPSS writes client log messages to a file with the following naming format, where date identifies the date that you ran the command:


Starting in version 1.4.1, GPSS writes progress messages for each Kafka job to a separate file in the server log directory. Progress logs are written to a file with this naming format:


jobname and jobid (max 8 characters each) identify the name and the identifier of the GPSS job, and date identifies the date that you ran the command.

Example GPSS log file names:

  • gpss_20181228.log
  • gpsscli_20181228.log
  • progress_jobk2_d577cf37_20200803.log

After GPSS creates a log file of a specific type, it appends all log messages written on *date* to the respective file.

Rotating the GPSS Server Log File

If the log file for a gpss server instance grows too large, you may choose to archive the current log and start fresh with an empty log file.

To prompt GPSS to rotate the server log file, you must:

  1. Rename the existing log file. For example:

    gpadmin@gpmaster$ mv <logdir>/gpss_<date>.log <logdir>/gpss_<date>.log.1
  2. Send the SIGUSR2 signal to the gpss server process. You can obtain the process id of a GPSS instance by running the ps command. For example:

    gpadmin@gpmaster$ ps -ef | grep gpss
    gpadmin@gpmaster$ kill -SIGUSR2 <gpss_pid>

    Note: There may be more than one gpss server process running on the system. Be sure to send the signal to the desired process.

    When it receives the signal, GPSS emits a log message that identifies the time at which it reset the log file. For example:

    ... -[INFO]:-Set gpss log file rotate at 20190911:20:59:36.093

Integrating with logrotate

You can configure and manage GPSS server log file rotation with the Linux logrotate utility.

This sample logrotate configuration rotates and compresses the log file of each gpss server instance running on the system weekly or when the file reaches 10MB in size. It operates on log files that are written to the default location:

/home/gpadmin/gpAdminLogs/gpss_*.log {
    rotate 5
    size 10M
        pkill -SIGUSR2 gpss

If this configuration is specified in a file named gpss_rotate.conf residing in the current working directory, you integrate with the Linux logrotate system with the following command:

$ logrotate -s status -d gpss_rotate.conf

You may choose to create a cron job to run this command daily.

Monitoring GPSS Service Instances

GPSS provides out-of-the-box integration with the Prometheus open-source system monitoring and alerting toolkit. Refer to Enabling Prometheus Metrics Collection for information about enabling and using this integration.

About GPSS Job Management

When you submit a GPSS job, you provide a name/identifier for the job. If you do not specify a job name, GPSS assigns and returns the base name of the load configuration file as the job name. You use this name to manage the job throughout its lifecycle.

GPSS uses a data source-specific combination of properties specified in a load configuration file to internally identify a job. For example, when it loads from a Kafka data source, GPSS uses the Kafka topic name, and the target Greenplum database, schema, and table names for internal job identification. GPSS creates internal and external tables for each job that are keyed off of these properties; these tables keep track of the progress of the load operation. GPSS considers any load configuration file submitted with the same value for these job-identifying properties to be the same internal job.

A gpss server instance keeps track of the status of each client job in memory. By default, this information is invocation-specific. When you stop the server instance, you must re-submit any job that you want to run when you next restart the instance.

You can configure the JobStore property block in the gpss.json server configuration file to instruct GPSS to retain job and job status information across invocations.

"JobStore": {
    "File": {
        "Directory": "<jobstore_dir>"

When you specify a JobStore:File:Directory property setting in the server configuration file, the GPSS server instance keeps track of, and writes job information to, the directory that you specify. If you stop the server instance, a new invocation will restore the jobs that were in progress when it last exited, loading the jobs in memory and restoring their last known state.

Shadowing the Greenplum Database Password

When you use GPSS to load data into Greenplum Database, you specify the Greenplum user/role password in the PASSWORD: property setting of a YAML-format load configuration file; see gpsscli.yaml.

You specify the Greenplum password in clear text. If your security requirements do not permit this, you can configure GPSS to encode and decode a shadow password string that the GPSS client and server use when communicating the Greenplum password.

Note: GPSS supports shadowing the Greenplum password only on load jobs that you submit and manage with the gpsscli subcommands. GPSS does not support shadowed passwords on load jobs that you submit with gpkafka load.

When you use this GPSS feature:

  1. (Optional) You configure a Shadow:Key in the gpss.json configuration file that you specify when you start the GPSS instance. For example:

        "Shadow": {
            "Key": "a_very_secret_key"
  2. You run the gpsscli shadow command on the ETL system to interactively generate the shadowed password. For example:

    $ gpsscli shadow --config gpss.json
    please input your password

    You can automate this step using a command similar to the following:

    $ echo changemeCHANGEMEchangeme | gpsscli shadow --config gpss.json | tail -1

    If you do not specify the --config gpss.json option, or this configuration file does not include a Shadow:Key setting, GPSS uses its default key to generate the shadow password string.

  3. You specify the shadow password string returned by gpsscli shadow in the PASSWORD: property setting of a gpsscli.yaml load configuration file. For example:

    DATABASE: testdb
    USER: testuser

    Always quote the complete shadow password string.

  4. You provide the load configuration file as an option to gpsscli submit or gpsscli load when you submit the job.

  5. The GPSS instance servicing the job uses its Shadow:Key, or the default key, to decode the shadowed password string specified in PASSWORD:, and connects with Greenplum Database.

Pulling Information from the Debug Server

When you specify a DebugPort in the gpss.json configuration file, or when you specify the ‑‑debug‑port option to the gpss command, GPSS starts a debug server on the local host. This server makes available additional debug information about the running GPSS instance, including the call stack and performance statistics.

You can use the curl command to view the types of information available (HTML output):

$ curl > debug_info.html

Or, use curl to view specific information:

$ curl > debug_heap
$ curl > debug_goroutine
$ curl > debug_block

The commands above gather information and write the heap, the call stack, and locking information each to a text file in the current working directory.

The GPSS debug server can also provide CPU profiling data. The following command gathers 10 seconds of CPU profile data and writes it in binary format to the output file named debug_cpu_profile:

$ curl > debug_cpu_profile

You may be asked to send the binary output file to support. Alternatively, you can run the Go Profiling Tool on the file to parse and graph the results:

$ go tool pprof debug_cpu_profile
(pprof) web

The web command creates a graph of the profile data in SVG format, and opens the graph in a web browser.

check-circle-line exclamation-circle-line close-line
Scroll to top icon