warpstream agent

warpstream agent

The warpstream agent subcommand can be used to administer the WarpStream agents.

The following table displays the available warpstream agent arguments.



Custom hostname value to advertise to service discovery for clustering purposes if the custom advertise strategy is selected


Which hostname strategy should be used the agent should advertise itself on. Auto means that it will try to automatically find an IP that makes sense. If you select custom them you have to also define -advertiseHostnameCustom. Currently supported strategy: [auto-ip4, auto-ip6, local, custom]. (default "auto-ip4")


Agent pool to register the agent under (default "apn_default")


API key for WarpStream cloud


How frequently to flush batches. Lower values reduce latency, higher values cost more money (default 250ms)


Object storage URL to write data to


The default port to use for the cluster wide environment (default 9999)


Virtual cluster to default to for all requests


Disable the consumer group offset metrics automatically published by default


Disable the logs collection sent to warpstream backend (enabled by default)


Whether the cluster wide environment should be enabled


Enable datadog metrics


Enable datadog profiling


Enable kafka server (default true)


Enable kinesis server, enabled by default (default true)


Enable prometheus metrics (default true)


Number of extra replicas for the distributed file cache. Helps improve availability and reduce errors when Agents shutdown ungracefully. You can override this to 0, but do not increase this value above 1 unless you know what you're doing. (default 1)


File cache size in bytes. Defaults to 0.5GiB/vCPU if left unmodified.


Amount of time to wait after receiving SIGTERM before exiting to allow graceful removal from service discovery (default 1m0s)


How often the agent should heartbeat the WarpStream backend. Recommended to not modify this.


Port to run HTTP handlers on (Kinesis, distributed file cache, prometheus metrics, etc) (default 8080)


Compression type to use for Fetch responses: none, gzip, snappy, lz4 (by default), zstd. This is only used if no compression is set explicitly, or if 'agent' type compress


Handle consumer group 'JoinGroup' and 'SyncGroup' requests in the backend instead of in the agent. When handled in the backend, the 'Rebalance Timeout' is always set to 10 seconds, whereas in the agent, it will be determined by client specifications. Enabling this option offers the advantage of reduced error potential and seamless integration of backend improvements and bug fixes. However, exercise caution when enabling it for large consumer groups, as a 10-second rebalance timeout may lead to extended rebalancing times and consequently, prolonged consumption pauses. Warning: Ensure uniformity within your agent pool regarding this setting. Having a mix of enabled and disabled settings may lead to rebalancing issues and potential disruptions.


Interval at which the Kafka connection assesses if the client-agent connection resides in the same Availability Zone (AZ). If they are not in the same AZ and there are agents available within the client's AZ, the connection is terminated. This approach encourages load balancing by prompting clients to re-query the magic URL and, consequently, connect to agents within their respective AZ. For this mechanism to function, clients should include 'waprstream_az=X' and 'warpstream_interzone_lb=true' in their clientID. (default 1m0s)


Time given to gracefully close the Kafka connection after the reconnect interval is reached.


Time after which the Kafka connection will be closed. This mechanism helps load balance the clients by forcing them to query the magic URL again. By resetting the connection periodically, clients are evenly distributed across available Kafka connections. (default 8760h0m0s)


Period of time at which topic metadata is refreshed. Unlike Kafka, this metadata cache refresh also affects the timestamp type associated with a stream. (default 1m0s)


Port to run the kafka server on (default 9092)


Interval for logging service status (default 15s)


Maximum number of concurrent requests (per CPU) allowed by the Kafka server


Address for WarpStream metadata backend (default "https://api.prod.us-east-1.warpstream.com")


Controls whether the agents will enforce that all connections are SASL authenticated. Will automatically disable Kinesis support if enabled


Roles that the agent should start (comma-separated) (default "proxy, jobs")

Last updated


Apache, Apache Kafka, Kafka, and associated open source project names are trademarks of the Apache Software Foundation. Kinesis is a trademark of Amazon Web Services.