> For the complete documentation index, see [llms.txt](https://docs.lenses.io/latest/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lenses.io/latest/deployment/configuration/hq/configuration-reference.md). # Configuration Reference Every setting HQ reads from config.yaml, with its default and whether it is required. HQ reads its configuration from a single YAML file, **config.yaml**. For a complete example, how to read secrets from environment variables, and how to check a file before starting HQ, see [HQ](/latest/deployment/configuration/hq.md). Only three settings are required: `database.host`, `database.database` and `license.key`. You must also set `license.acceptEULA` to `true`, or HQ will not start. Every other setting has a default. {% hint style="warning" %} HQ ignores keys it does not recognise. A misspelled key does not cause an error; the setting keeps its default value. To check which values HQ uses, see [Check a configuration file](/latest/deployment/configuration/hq.md#check-a-configuration-file). {% endhint %} Durations are Go duration strings, such as `30s`, `10m` or `720h`. Valid units are `ns`, `us`, `ms`, `s`, `m` and `h`; there is no unit for days. *** ## Config Contains all config items. It has the following fields: | Name | Required | Default | Type | Description | | ---------- | -------- | ------- | ----------------------------------- | -------------------------------------------- | | `http` | No | `{}` | [`HTTPConfig`](#httpconfig) | Configures the HTTP server. | | `agents` | No | `{}` | [`AgentsConfig`](#agentsconfig) | Controls the agent handling. | | `auth` | No | `{}` | [`AuthConfig`](#authconfig) | Configures authentication and authorisation. | | `database` | Yes | n/a | [`DatabaseConfig`](#databaseconfig) | Configures database settings. | | `logger` | No | `{}` | [`LoggerConfig`](#loggerconfig) | Sets the logger behaviour. | | `metrics` | No | `{}` | [`MetricsConfig`](#metricsconfig) | Controls the metrics settings. | | `license` | Yes | n/a | [`License`](#license) | Holds the license key. | | `audit` | No | `{}` | [`AuditConfig`](#auditconfig) | Configures API audit logging. | Advanced fields, which most deployments leave at their defaults: | Name | Required | Default | Type | Description | | ---------------- | -------- | ------- | ----------------------------------------------- | ---------------------------------------------------------- | | `consumerGroups` | No | `{}` | [`ConsumerGroupsConfig`](#consumergroupsconfig) | Tunes HQ's copy of the consumer groups. | | `environments` | No | `{}` | [`EnvironmentsConfig`](#environmentsconfig) | Tunes how HQ refreshes information about its environments. | | `runtime` | No | `{}` | [`RuntimeConfig`](#runtimeconfig) | Configures how the HQ process uses memory. | | `kafka` | No | `{}` | [`KafkaConfig`](#kafkaconfig) | Configures Kafka topic data operations. | | `proxy` | No | `{}` | [`ProxyConfig`](#proxyconfig) | Configures how HQ forwards API requests to Agents. | | `features` | No | `{}` | [`FeaturesConfig`](#featuresconfig) | Toggles optional product features. | ### Config: http Configures the HTTP server. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#httpconfig). ### Config: agents Controls the agent handling. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#agentsconfig). ### Config: auth Configures authentication and authorisation. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#authconfig). ### Config: database Configures database settings. This configuration section is required. Please refer [here](#databaseconfig) for its structure. ### Config: logger Sets the logger behaviour. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#loggerconfig). ### Config: metrics Controls the metrics settings. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#metricsconfig). ### Config: license Holds the license key. This configuration section is required. Please refer [here](#license) for its structure. ### Config: audit Configures API audit logging. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#auditconfig). ### Config: consumerGroups Tunes HQ's copy of the consumer groups. HQ keeps a copy of every environment's consumer groups, offsets and lag in its database, and refreshes it by polling the Agents. The UI and API read consumer groups from this copy. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#consumergroupsconfig). ### Config: environments Tunes how HQ refreshes information about its environments. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#environmentsconfig). ### Config: runtime Configures how the HQ process uses memory. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#runtimeconfig). ### Config: kafka Configures Kafka topic data operations. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#kafkaconfig). ### Config: proxy Configures how HQ forwards API requests to Agents. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#proxyconfig). ### Config: features Toggles optional product features. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#featuresconfig). *** ## HTTPConfig Configures the HTTP server. It has the following fields: | Name | Required | Default | Type | Description | | --------- | -------- | ------- | ------------------------- | -------------------------------------------- | | `address` | No | `:8082` | `string` | Sets the address the HTTP server listens at. | | `tls` | No | `{}` | [`TLSConfig`](#tlsconfig) | Contains TLS configuration. | Advanced fields, which most deployments leave at their defaults: | Name | Required | Default | Type | Description | | ------------------------------- | -------- | ------- | --------- | ---------------------------------------------------------------- | | `accessControlAllowOrigin` | No | `["*"]` | `strings` | Sets the value of the "Access-Control-Allow-Origin" header. | | `accessControlAllowCredentials` | No | `false` | `boolean` | Sets the value of the "Access-Control-Allow-Credentials" header. | | `secureSessionCookies` | No | `true` | `boolean` | Sets the "Secure" attribute on session cookies. | | `sessionCookieDomain` | No | `""` | `string` | Defines the host to which session cookies will be sent. | | `strictTransportSecurity` | No | `false` | `boolean` | Enables the Strict-Transport-Security header. | | `h2c` | No | `false` | `boolean` | Enables unencrypted HTTP/2. | ### HTTPConfig: address Sets the address the HTTP server listens at. Optional. If not set, it will default to `:8082`. Example value: `127.0.0.1:80`. ### HTTPConfig: tls Contains TLS configuration. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#tlsconfig). ### HTTPConfig: accessControlAllowOrigin Sets the value of the "Access-Control-Allow-Origin" header. This is only relevant when serving the backend from a different origin than the UI. Optional. If not set, it will default to `["*"]`. ### HTTPConfig: accessControlAllowCredentials Sets the value of the "Access-Control-Allow-Credentials" header. This is only relevant when serving the backend from a different origin than the UI. Optional. If not set, it will default to `false`. ### HTTPConfig: secureSessionCookies Sets the "Secure" attribute on authentication session cookies. Browsers then send these cookies only over HTTPS, or to localhost. If you serve HQ over plain HTTP, set this to false, or users cannot log in. Optional. If not set, it will default to `true`. ### HTTPConfig: sessionCookieDomain Defines the host to which session cookies will be sent. If not specified, it defaults to the host of the current document URL, not including subdomains. Please refer to for more information. Optional. If not set, it will default to `""`. ### HTTPConfig: strictTransportSecurity When enabled, sets the Strict-Transport-Security header to "max-age=31536000; includeSubDomains", which tells browsers to connect to this host and all its subdomains only over HTTPS, for one year. WARNING: browsers remember this for the full year. If you enable it while HQ is served over HTTP, users cannot reach HQ until the period expires or they clear the browser's HSTS data. Optional. If not set, it will default to `false`. Example value: `false`. ### HTTPConfig: h2c Enables HTTP/2 over unencrypted connections. Has an effect only when TLS is disabled. Optional. If not set, it will default to `false`. *** ## TLSConfig Contains TLS configuration. It has the following fields: | Name | Required | Default | Type | Description | | --------- | ---------- | ------- | --------- | ------------------------------------------ | | `enabled` | No | `false` | `boolean` | Enables or disables TLS. | | `cert` | If enabled | `""` | `string` | Sets the PEM formatted public certificate. | | `key` | If enabled | `""` | `string` | Sets the PEM formatted private key. | Advanced fields, which most deployments leave at their defaults: | Name | Required | Default | Type | Description | | ------------- | -------- | ------- | --------- | ---------------------------- | | `verboseLogs` | No | `false` | `boolean` | Enables verbose TLS logging. | ### TLSConfig: enabled Enables or disables TLS. Optional. If not set, it will default to `false`. Example value: `false`. ### TLSConfig: cert Sets the PEM formatted public certificate. This field is required if `enabled` is set to true. Example value: ``` -----BEGIN CERTIFICATE----- EXampLeRanDoM ... -----END CERTIFICATE----- ``` ### TLSConfig: key Sets the PEM formatted private key. This field is required if `enabled` is set to true. Example value: ``` -----BEGIN PRIVATE KEY----- ExAmPlErAnDoM ... -----END PRIVATE KEY----- ``` ### TLSConfig: verboseLogs Enables additional logging of TLS settings and events at debug level. The information presented might be a bit too much for day to day use but can provide extra information for troubleshooting TLS configuration. Optional. If not set, it will default to `false`. *** ## AgentsConfig Controls the agent handling. It has the following fields: | Name | Required | Default | Type | Description | | --------- | -------- | -------- | ------------------------- | --------------------------------------------- | | `address` | No | `:10000` | `string` | Sets the address the agent server listens at. | | `tls` | No | `{}` | [`TLSConfig`](#tlsconfig) | Contains TLS configuration. | Advanced fields, which most deployments leave at their defaults: | Name | Required | Default | Type | Description | | ------ | -------- | ------- | ------------------------------------- | ---------------------------------- | | `grpc` | No | `{}` | [`AgentGRPCConfig`](#agentgrpcconfig) | Contains Agent gRPC configuration. | ### AgentsConfig: address Sets the address the agent server listens at. Optional. If not set, it will default to `:10000`. Example value: `127.0.0.1:3000`. ### AgentsConfig: tls Contains TLS configuration. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#tlsconfig). ### AgentsConfig: grpc Contains Agent gRPC configuration. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#agentgrpcconfig). *** ## AgentGRPCConfig Contains Agent gRPC configuration. It has the following fields: | Name | Required | Default | Type | Description | | ------------------------- | -------- | ----------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `apiMaxRecvMessageSize` | No | `33554432` | `integer` | Maximum size in bytes of an API response that HQ forwards from an agent. | | `agentMaxRecvMessageSize` | No | `104857600` | `integer` | Maximum size in bytes of a single gRPC response HQ will accept from an agent over the agent link (e.g. consumer-group describe/offset polls). Large environments (many partitions per consumer group) can exceed gRPC's 4 MB default; raise this if agent polls fail with ResourceExhausted. | ### AgentGRPCConfig: apiMaxRecvMessageSize Maximum size in bytes of an API response that HQ forwards from an agent. Optional. If not set, it will default to `33554432`. ### AgentGRPCConfig: agentMaxRecvMessageSize Maximum size in bytes of a single gRPC response HQ will accept from an agent over the agent link (e.g. consumer-group describe/offset polls). Large environments (many partitions per consumer group) can exceed gRPC's 4 MB default; raise this if agent polls fail with ResourceExhausted. Optional. If not set, it will default to `104857600`. *** ## AuthConfig Configures authentication and authorisation. It has the following fields: | Name | Required | Default | Type | Description | | ----------------- | -------- | ------- | ------------------------------------ | --------------------------------- | | `administrators` | No | `[]` | `strings` | Grants root access to principals. | | `users` | No | `[]` | [`UserCredentials`](#usercredential) | Contains user-credential pairs. | | `sessionDuration` | No | `24h` | `string` | Sets the duration of a session. | | `saml` | No | `{}` | [`SAMLConfig`](#samlconfig) | Contains SAML2 IdP configuration. | | `oauth2` | No | `{}` | [`OAuth2Config`](#oauth2config) | Holds settings for OAuth 2.0. | ### AuthConfig: administrators Lists the names of the principals (users, service accounts) that have root access. Access control allows any API operation performed by such principals. Optional. If not set, it will default to `[]`. ### AuthConfig: users Contains user-credential pairs that allow users to login using password-based authentication. On start, HQ creates a corresponding User if a listed user does not exist. Optional. If not set, it will default to `[]`. ### AuthConfig: sessionDuration Sets the duration of a session. After successful authentication via SSO or username/password, a session cookie is issued as a temporary proof of authentication. This setting controls the lifetime of such cookies, after which a new check-in with the SSO provider (or entering the password for non-SSO) is requested. The duration is a string that follows the Go time.Duration format. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". Optional. If not set, it will default to `24h`. Example value: `20h30m`. ### AuthConfig: saml Contains SAML2 IdP configuration. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#samlconfig). ### AuthConfig: oauth2 Holds settings for OAuth 2.0 in HQ, including the optional embedded authorization server. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#oauth2config). *** ## UserCredential Bundles a username with a bcrypted password-hash. It has the following fields: | Name | Required | Default | Type | Description | | ---------- | -------- | ------- | -------- | ---------------------------------- | | `username` | Yes | n/a | `string` | Contains the username. | | `password` | Yes | n/a | `string` | Contains the bcrypt password hash. | ### UserCredential: username Contains the username. If a user with this username does not exist, it is created on start. Example value: `admin`. ### UserCredential: password Contains the bcrypt hash of the password, never the password itself. The Lenses CLI ("lenses utils hash-password") can calculate the hash, as can tools like caddy or htpasswd. Example value: `$2a$12$example123...`. *** ## SAMLConfig Contains SAML2 IdP configuration. It has the following fields: | Name | Required | Default | Type | Description | | ----------------------- | ---------- | -------- | ----------------------------------------------------------- | ------------------------------------------ | | `enabled` | No | `false` | `boolean` | Enables or disables SAML. | | `metadata` | If enabled | `""` | `string` | Contains the IdP issued XML metadata blob. | | `authnRequestSignature` | No | `{}` | [`SAMLAuthnRequestSignatures`](#samlauthnrequestsignatures) | Configures SAML AuthnRequest signing. | | `baseURL` | If enabled | `""` | `string` | Defines base URL of HQ for IdP redirects. | | `entityID` | If enabled | `""` | `string` | Defines the Entity ID. | | `groupAttributeKey` | No | `groups` | `string` | Sets the attribute name for group names. | | `userCreationMode` | No | `manual` | `string` | Controls SSO user creation. | | `groupMembershipMode` | No | `manual` | `string` | Controls SSO user-group assignment. | Advanced fields, which most deployments leave at their defaults: | Name | Required | Default | Type | Description | | ----------- | -------- | ------- | -------- | ------------------------------------------------------------- | | `uiRootURL` | No | `/` | `string` | Controls where to redirect to upon successful authentication. | ### SAMLConfig: enabled Enables or disables SAML. Optional. If not set, it will default to `false`. Example value: `false`. ### SAMLConfig: metadata Contains the IdP issued XML metadata blob. This field is required if `enabled` is set to true. Example value: ``. ### SAMLConfig: authnRequestSignature Configures SAML AuthnRequest signing. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#samlauthnrequestsignatures). ### SAMLConfig: baseURL Defines the base URL of Lenses HQ; the IdP redirects back to here on success. This field is required if `enabled` is set to true. Example value: `https://hq.example.com`. ### SAMLConfig: entityID Defines HQ's SAML entity ID. It must match the entity ID configured for HQ in the IdP. This field is required if `enabled` is set to true. Example value: `https://hq.example.com`. ### SAMLConfig: groupAttributeKey Sets the attribute name from which group names are extracted in the SAML2 assertions. Different providers use different names. Okta, Keycloak and Google use "groups". OneLogin uses "roles". Microsoft Entra ID (Azure) uses "". Optional. If not set, it will default to `groups`. Example value: `groups`. ### SAMLConfig: userCreationMode Controls how the creation of users should be handled in relation to SSO information. With the 'manual' mode, only users that currently exist in HQ can login. Users that do not exist are rejected. With the 'sso' mode, users that do not exist are automatically created. Allowed values are `manual` or `sso`. Optional. If not set, it will default to `manual`. ### SAMLConfig: groupMembershipMode Controls how the management of a user's group membership should be handled in relation to SSO information. With the 'manual' mode, the information about the group membership returned from an Identity Provider will not be used and a user will only be a member of groups that were explicitly assigned to them locally. With the 'sso' mode, group information from Identity Provider (IdP) will be used. On login, a user's group membership is set to the groups listed in the IdP. Groups that do not exist in HQ are ignored. Allowed values are `manual` or `sso`. Optional. If not set, it will default to `manual`. ### SAMLConfig: uiRootURL Controls where the backend redirects to after having received a valid SAML2 assertion. Optional. If not set, it will default to `/`. Example value: `/`. *** ## SAMLAuthnRequestSignatures Configures SAML AuthnRequest signing. It has the following fields: | Name | Required | Default | Type | Description | | --------- | -------- | ------- | --------- | ------------------------------------------ | | `enabled` | No | `true` | `boolean` | Enables AuthnRequest signing. | | `cert` | No | `""` | `string` | Sets the AuthnRequest signing certificate. | | `key` | No | `""` | `string` | Sets the AuthnRequest signing private key. | ### SAMLAuthnRequestSignatures: enabled Enables signing the AuthnRequest that HQ sends to the IdP. Optional. If not set, it will default to `true`. Example value: `true`. ### SAMLAuthnRequestSignatures: cert Sets the PEM formatted AuthnRequest signing certificate. If provided, the key needs to be provided as well. If neither is provided while AuthnRequest signing is enabled, HQ generates a new self-signed key pair every time it starts; provide your own if the IdP checks signatures against a known certificate. Optional. If not set, it will default to `""`. Example value: ``` -----BEGIN CERTIFICATE----- EXampLeRanDoM ... -----END CERTIFICATE----- ``` ### SAMLAuthnRequestSignatures: key Sets the PEM formatted AuthnRequest signing private key. If provided, the cert needs to be provided as well. If neither is provided while AuthnRequest signing is enabled, HQ generates a new self-signed key pair every time it starts; provide your own if the IdP checks signatures against a known certificate. Optional. If not set, it will default to `""`. Example value: ``` -----BEGIN PRIVATE KEY----- ExAmPlErAnDoM ... -----END PRIVATE KEY----- ``` *** ## OAuth2Config Holds settings for OAuth 2.0 in HQ, including the optional embedded authorization server. It has the following fields: | Name | Required | Default | Type | Description | | --------------------- | -------- | ------- | --------------------------------------------------------------------- | --------------------------------------------------- | | `authorizationServer` | No | `{}` | [`OAuth2AuthorizationServerConfig`](#oauth2authorizationserverconfig) | Controls HQ's OAuth2 embedded authorization server. | ### OAuth2Config: authorizationServer Controls HQ's OAuth2 embedded authorization server. Allows using OAuth2 without running a separate authorization server. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#oauth2authorizationserverconfig). *** ## OAuth2AuthorizationServerConfig Controls HQ's OAuth2 embedded authorization server. Allows using OAuth2 without running a separate authorization server. It has the following fields: | Name | Required | Default | Type | Description | | ----------- | ---------- | ------- | --------- | --------------------------------- | | `enabled` | No | `false` | `boolean` | Enables the authorization server. | | `issuerURL` | If enabled | `""` | `string` | Sets the issuer identifier. | Advanced fields, which most deployments leave at their defaults: | Name | Required | Default | Type | Description | | ------------------------------ | -------- | -------- | --------- | --------------------------------------------- | | `authorizationLifetime` | No | `2160h` | `string` | Sets the maximum authorization lifetime. | | `requirePKCE` | No | `true` | `boolean` | Requires PKCE for all authorization requests. | | `dcr` | No | `false` | `boolean` | Enables dynamic client registration. | | `unauthenticatedIntrospection` | No | `false` | `boolean` | Enables unauthenticated token introspection. | | `redirectMethod` | No | `header` | `string` | Controls the redirection mechanism. | ### OAuth2AuthorizationServerConfig: enabled Enables HQ's built-in OAuth 2.0 authorization server. Optional. If not set, it will default to `false`. ### OAuth2AuthorizationServerConfig: issuerURL Sets the OAuth2 Authorization Server issuer identifier (RFC 8414). This is the URL that appears in the "issuer" field of the well-known metadata and must match the URL clients use to reach HQ. This field is required if `enabled` is set to true. Example value: `https://hq.example.com`. ### OAuth2AuthorizationServerConfig: authorizationLifetime The absolute maximum lifetime of an authorization. After this period, the user must re-authorize. Refresh tokens issued under an authorization that has exceeded this lifetime are rejected. Go time.Duration format. Optional. If not set, it will default to `2160h`. ### OAuth2AuthorizationServerConfig: requirePKCE When enabled, all authorization requests must include a code\_challenge (S256). OAuth 2.1 mandates PKCE; enable this to enforce it independently of the protocol version. Optional. If not set, it will default to `true`. ### OAuth2AuthorizationServerConfig: dcr Enables the dynamic client registration endpoint (RFC 7591). When enabled, OAuth2 clients can register themselves without manual configuration. Optional. If not set, it will default to `false`. ### OAuth2AuthorizationServerConfig: unauthenticatedIntrospection Allows unauthenticated token introspection requests. Per RFC 7662, the token introspection endpoint must be authenticated. In controlled environments (e.g. during development) one could allow unauthenticated requests. Optional. If not set, it will default to `false`. ### OAuth2AuthorizationServerConfig: redirectMethod Controls how HQ issues redirects. "header" uses an HTTP redirect status with a Location header. "body" returns an HTML page that performs the redirect. Use "body" when a proxy in front of HQ rewrites redirect responses. Allowed values are `header` or `body`. Optional. If not set, it will default to `header`. *** ## DatabaseConfig Configures database settings. It has the following fields: | Name | Required | Default | Type | Description | | ---------- | -------- | ------- | -------------------- | --------------------------------------------------------------------------- | | `host` | Yes | n/a | `string` | Sets the name of the host to connect to. | | `username` | No | `""` | `string` | Sets the username to authenticate as. | | `password` | No | `""` | `string` | Sets the password to authenticate as. | | `database` | Yes | n/a | `string` | Sets the database to use. | | `schema` | No | `""` | `string` | Sets the schema to use. If empty, PostgreSQL's default search path is used. | | `TLS` | No | `false` | `boolean` | Enables TLS. | | `params` | No | `{}` | `DBConnectionParams` | Provides fine-grained control. | Advanced fields, which most deployments leave at their defaults: | Name | Required | Default | Type | Description | | ------------------------ | -------- | ------- | --------- | ----------------------------------------------------------------------- | | `statementTimeout` | No | `30s` | `string` | Sets the server-side statement timeout for interactive queries. | | `maxConns` | No | `0` | `integer` | Sets the max connections for the main interactive query pool. | | `pollerPoolMaxConns` | No | `4` | `integer` | Sets the max connections for the background consumer-group poller pool. | | `pollerStatementTimeout` | No | `10m` | `string` | Sets the server-side statement timeout for the background poller pool. | ### DatabaseConfig: host Sets the name of the host to connect to. A comma-separated list of host names is also accepted; each host name in the list is tried in order. Example value: `postgres:5432`. ### DatabaseConfig: username Sets the username to authenticate as. Optional. If not set, it will default to `""`. Example value: `andrew`. ### DatabaseConfig: password Sets the password to authenticate as. Optional. If not set, it will default to `""`. Example value: `my-password`. ### DatabaseConfig: database Sets the database to use. Example value: `my-database`. ### DatabaseConfig: schema Sets the schema to use. If empty, PostgreSQL's default search path is used. Optional. If not set, it will default to `""`. Example value: `my-schema`. ### DatabaseConfig: TLS Enables TLS. In PostgreSQL connection string terms, setting TLS to `false` corresponds to `sslmode=disable`; setting TLS to `true` corresponds to `sslmode=verify-full`. For more fine-grained control, specify `sslmode` in the params which takes precedence. Optional. If not set, it will default to `false`. Example value: `true`. ### DatabaseConfig: params Contains connection string parameters as key/values pairs. It allows fine-grained control of connection settings. The parameters can be found here: Optional. If not set, it will default to `{}`. Example value: `{"application_name":"example"}`. ### DatabaseConfig: statementTimeout Sets the PostgreSQL server-side statement\_timeout applied to every connection in HQ's main query pool. Any single query running longer than this is cancelled by the server, which frees the connection instead of letting a slow query pin it under load. The database health check uses a separate, dedicated connection and database migrations run on their own connection; both are exempt from this timeout so long-running schema changes are not affected. The duration follows the Go time.Duration format (e.g., "30s", "1m"). An empty string or "0" disables the timeout. Consumer group reads have a shorter, separate limit: consumerGroups.readTimeout. Optional. If not set, it will default to `30s`. ### DatabaseConfig: maxConns Sets the maximum number of connections in HQ's main interactive query pool (the pool that serves API reads and writes). When unset or 0, the pool keeps the pgx driver's derived default (4 x GOMAXPROCS, minimum 4); the effective value is logged at startup so it is visible. Set it to cap the main pool explicitly so its size can be budgeted against the database's connection limit. HQ opens up to four pools per process: this main pool, the background consumer-group poller pool (pollerPoolMaxConns, default 4), the health-check pool (2), and the index maintenance pool (2, only while consumerGroups.indexMaintenance.enabled is true). Size them together so that their sum, multiplied by the number of HQ replicas, stays within the database's max\_connections. The "reindex-cg-partition" command opens its own index maintenance pool while it runs. Optional. If not set, it will default to `0`. ### DatabaseConfig: pollerPoolMaxConns Sets the maximum number of connections in the dedicated Postgres pool used by the background consumer-group poller (poll, compose and write). Isolating the poller on its own pool keeps its background write load from contending with interactive API reads served by the main query pool, so a busy poll can no longer starve live grid reads (and vice versa). Set it to at least consumerGroups.refreshWorkers (>= that count) so every concurrent env compose gets a connection rather than queueing on the pool; otherwise the pool, not the worker count, becomes the bottleneck. Size it together with HQ's other pools so that their total stays within the database's max\_connections; see maxConns. The poller pool carries its own server-side statement\_timeout (pollerStatementTimeout), independent of the main query pool. Optional. If not set, it will default to `4`. ### DatabaseConfig: pollerStatementTimeout Sets the PostgreSQL server-side statement\_timeout applied to every connection in the dedicated background consumer-group poller pool. This is kept separate from the main query pool's statementTimeout so the poller's legitimate bulk read-model upserts (which can run long on very large, many-partition environments) are not cancelled by the much shorter interactive read timeout, while interactive reads on the main pool stay protected. The default is a large-but-finite value so a genuinely stuck background statement is still eventually cancelled rather than pinning one of the pool's few connections forever. The duration follows the Go time.Duration format (e.g., "10m", "30m"). An empty string or "0" disables the timeout entirely. Optional. If not set, it will default to `10m`. *** ## LoggerConfig Sets the logger behaviour. It has the following fields: | Name | Required | Default | Type | Description | | ------- | -------- | ------- | -------- | ------------------------------------------- | | `mode` | No | `text` | `string` | Controls the format of the logger's output. | | `level` | No | `info` | `string` | Controls the level of the logger. | ### LoggerConfig: mode Controls the format of the logger's output. Allowed values are `text` or `json`. Optional. If not set, it will default to `text`. ### LoggerConfig: level Controls the level of the logger. Allowed values are `info` or `debug`. Optional. If not set, it will default to `info`. *** ## MetricsConfig Controls the metrics settings. It has the following fields: | Name | Required | Default | Type | Description | | ------------------- | -------- | ------- | -------- | ---------------------------- | | `prometheusAddress` | No | `:9090` | `string` | Sets the Prometheus address. | ### MetricsConfig: prometheusAddress Sets the address at which Prometheus metrics are served. Exposes `GET /metrics` (HQ process telemetry) and `GET /kafka-metrics` (consumer group lag and state, in the same shape as the Lenses Agent served them). Optional. If not set, it will default to `:9090`. *** ## License Holds the license key. It has the following fields: | Name | Required | Default | Type | Description | | ------------ | -------- | ------- | --------- | --------------------------- | | `key` | Yes | n/a | `string` | Sets the license key. | | `acceptEULA` | No | `false` | `boolean` | Marks the EULA as accepted. | ### License: key Sets the license key. An HQ key starts with `license_key_`. Example value: `license_key_axb123...`. ### License: acceptEULA Marks the end-user license agreement (EULA) as accepted. You can find the EULA at: . HQ does not start unless this is set to true. Optional. If not set, it will default to `false`. Example value: `false`. *** ## AuditConfig Configures API audit logging. It has the following fields: | Name | Required | Default | Type | Description | | ----------------- | -------- | ------- | --------- | ------------------------------------ | | `enabled` | No | `false` | `boolean` | Enables API audit logging. | | `retentionPeriod` | No | `""` | `string` | Sets the audit log retention period. | ### AuditConfig: enabled Enables or disables API audit logging. Optional. If not set, it will default to `false`. ### AuditConfig: retentionPeriod Automatically delete audit logs older than this duration. The duration follows the Go time.Duration format (e.g., "720h" for 30 days). Empty string or "0" disables automatic deletion. Optional. If not set, it will default to `""`. *** ## ConsumerGroupsConfig Tunes HQ's copy of the consumer groups. HQ keeps a copy of every environment's consumer groups, offsets and lag in its database, and refreshes it by polling the Agents. The UI and API read consumer groups from this copy. It has the following fields: | Name | Required | Default | Type | Description | | ----------------------- | -------- | ------- | ------------------------------------------------------- | -------------------------------------------------------------------- | | `pollInterval` | No | `30s` | `string` | How often HQ refreshes an environment's consumer groups. | | `maxPartitionsPerBatch` | No | `20000` | `integer` | Maximum partitions HQ processes in one batch. | | `composeTimeout` | No | `2m` | `string` | Time limit for collecting one environment's data. | | `composeConcurrency` | No | `1` | `integer` | Batches of one environment that HQ collects at the same time. | | `chunkConcurrency` | No | `4` | `integer` | Requests to one Agent that HQ sends at the same time within a batch. | | `refreshWorkers` | No | `4` | `integer` | How many environments HQ refreshes at the same time. | | `indexMaintenance` | No | `{}` | [`CGIndexMaintenanceConfig`](#cgindexmaintenanceconfig) | Scheduled rebuild of the consumer group indexes. | | `readTimeout` | No | `10s` | `string` | Time limit for a consumer group read by the UI or API. | ### ConsumerGroupsConfig: pollInterval How often HQ refreshes each environment's consumer groups from its Agent. A lower value means fresher data, at the cost of more traffic to the Agents. The duration follows the Go time.Duration format (e.g., "15s", "1m"). Values below 1s are rejected. Optional. If not set, it will default to `30s`. ### ConsumerGroupsConfig: maxPartitionsPerBatch Maximum number of topic partitions HQ collects and writes in one batch. HQ packs whole consumer groups into a batch until it reaches this limit, writes the batch, and then starts the next one. This keeps memory use bounded however many partitions an environment has. HQ splits a single group that is larger than the limit across batches. Lower it if HQ is short of memory; raise it to reduce the number of database transactions per environment. Optional. If not set, it will default to `20000`. ### ConsumerGroupsConfig: composeTimeout Maximum time HQ spends collecting one environment's consumer group data from its Agent in one refresh. If it is exceeded, HQ marks the environment's data as stale and retries on the next refresh. Follows the Go time.Duration format (e.g., "2m", "5m"). Optional. If not set, it will default to `2m`. ### ConsumerGroupsConfig: composeConcurrency How many batches of one environment HQ collects at the same time. With the default of 1, HQ collects and writes one batch after another. This setting only matters for environments that need more than one batch. Raise it when collecting data, not writing it, is the slow part, typically because the Kafka cluster responds slowly: HQ then collects the next batch while it writes the current one. HQ always writes batches one at a time and in order. Peak memory grows to roughly this value times maxPartitionsPerBatch. Optional. If not set, it will default to `1`. ### ConsumerGroupsConfig: chunkConcurrency How many requests HQ sends to one Agent at the same time while collecting a batch. This matters for environments with many consumer groups or many partitions, where a batch needs many requests. The default of 4 shortens the refresh for such environments. Raising it further uses more memory in HQ and puts more load on the Agent. Optional. If not set, it will default to `4`. ### ConsumerGroupsConfig: refreshWorkers How many environments HQ refreshes and writes to the database at the same time. This caps the write load on PostgreSQL. Raise it to bring many environments up to date faster, for example after HQ starts. Set database.pollerPoolMaxConns to at least this value, so that every worker gets a database connection. Optional. If not set, it will default to `4`. ### ConsumerGroupsConfig: indexMaintenance Periodically rebuilds the indexes of HQ's consumer group table. HQ rewrites this table on every refresh, so its indexes grow faster than PostgreSQL's autovacuum can reclaim space, especially on disks with limited IOPS. HQ therefore rebuilds them with REINDEX INDEX CONCURRENTLY, which does not block reads or refreshes. Rebuilds never overlap, and use their own connection pool. The same rebuild can also be run from a cron job with the "reindex-cg-partition" command. This configuration section is optional. If not provided, its values are set to the defaults described in its [structure](#cgindexmaintenanceconfig). ### ConsumerGroupsConfig: readTimeout Maximum time a consumer group read by the UI or API may run against PostgreSQL. When it is exceeded, HQ cancels the query and the request fails with HTTP 503, instead of holding a database connection for a long time. Raise it if you have consumer groups with tens of thousands of partitions, where even a well-indexed read can take longer. Lower it to fail faster and protect the connection pool under load. Follows the Go time.Duration format (e.g., "10s", "30s"). This limit is shorter than, and separate from, database.statementTimeout, so a slow consumer group read fails with a specific error first. Optional. If not set, it will default to `10s`. *** ## CGIndexMaintenanceConfig Periodically rebuilds the indexes of HQ's consumer group table. HQ rewrites this table on every refresh, so its indexes grow faster than PostgreSQL's autovacuum can reclaim space, especially on disks with limited IOPS. HQ therefore rebuilds them with REINDEX INDEX CONCURRENTLY, which does not block reads or refreshes. Rebuilds never overlap, and use their own connection pool. The same rebuild can also be run from a cron job with the "reindex-cg-partition" command. It has the following fields: | Name | Required | Default | Type | Description | | ------------------ | -------- | ------- | --------- | ---------------------------------------------------------------- | | `enabled` | No | `true` | `boolean` | Enables the scheduled rebuild inside HQ. | | `interval` | No | `60m` | `string` | How often the rebuild runs. | | `minGrowthPercent` | No | `25` | `integer` | Skips a rebuild until the indexes have grown by this percentage. | ### CGIndexMaintenanceConfig: enabled Enables the scheduled rebuild inside HQ. The "reindex-cg-partition" command works regardless of this setting. Disable the scheduled rebuild only if you run that command, for example from cron, instead. Optional. If not set, it will default to `true`. ### CGIndexMaintenanceConfig: interval How often the rebuild runs, independently of consumerGroups.pollInterval. If a rebuild is still running when the next one is due, HQ skips the new one. Follows the Go time.Duration format (e.g. "60m", "2h"). Values below 1m are rejected. Optional. If not set, it will default to `60m`. ### CGIndexMaintenanceConfig: minGrowthPercent Skips a scheduled rebuild until the indexes have grown by this percentage since the last rebuild. With the default of 25, HQ rebuilds once the indexes reach 1.25 times their size right after the previous rebuild. Set to 0 to rebuild on every interval. HQ always rebuilds on the first run. Optional. If not set, it will default to `25`. *** ## EnvironmentsConfig Tunes how HQ refreshes information about its environments. It has the following fields: | Name | Required | Default | Type | Description | | ---------------- | -------- | ------- | --------- | ---------------------------------------------------- | | `refreshWorkers` | No | `4` | `integer` | How many environments HQ refreshes at the same time. | ### EnvironmentsConfig: refreshWorkers How many environments' Agent information, such as metrics and metadata, HQ refreshes at the same time. When all workers are busy, HQ defers the remaining environments to the next round; the hq\_envpoller\_worker\_blocks\_total metric counts these deferrals. Raise it when many environments are connected. Refreshing many small environments is cheap, so a higher value is safe. This is independent of consumerGroups.refreshWorkers. Optional. If not set, it will default to `4`. *** ## RuntimeConfig Configures how the HQ process uses memory. It has the following fields: | Name | Required | Default | Type | Description | | -------------------- | -------- | ------- | --------- | ----------------------------------------------------------------- | | `memoryLimitPercent` | No | `90` | `integer` | Soft memory limit, as a percentage of the container memory limit. | ### RuntimeConfig: memoryLimitPercent Sets the Go runtime's soft memory limit (GOMEMLIMIT) to this percentage of the container's memory limit. As HQ's memory use approaches it, the garbage collector works harder to stay below it, instead of letting memory grow until the container is killed for running out of memory. It is not a hard limit, and it covers only memory managed by Go, not all memory the process uses; that is why it sits below the container limit. Keep it well above HQ's normal memory use, or the garbage collector uses a lot of CPU. Set to 0 to disable. A GOMEMLIMIT environment variable takes precedence. Has no effect when HQ cannot detect a container memory limit. Optional. If not set, it will default to `90`. *** ## KafkaConfig Configures Kafka topic data operations. It has the following fields: | Name | Required | Default | Type | Description | | ---------------------- | -------- | ---------- | --------- | ------------------------------------------------------------------------- | | `maxRecordsPerRequest` | No | `1000` | `integer` | Default and upper bound for GetKafkaTopicRecords' max\_records parameter. | | `maxBytesPerRequest` | No | `33554432` | `integer` | Default and upper bound for GetKafkaTopicRecords' max\_bytes parameter. | ### KafkaConfig: maxRecordsPerRequest Maximum number of records a single GetKafkaTopicRecords response may contain. When reached, the response is truncated and clients paginate via next\_offset. Callers may request a smaller cap via the endpoint's max\_records query parameter; requests for a larger cap are silently clamped down to this value, which is always the upper bound. Optional. If not set, it will default to `1000`. ### KafkaConfig: maxBytesPerRequest Maximum cumulative size in bytes a single GetKafkaTopicRecords response may contain. When reached, the response is truncated and clients paginate via next\_offset. Callers may request a smaller cap via the endpoint's max\_bytes query parameter; requests for a larger cap are silently clamped down to this value, which is always the upper bound. Optional. If not set, it will default to `33554432`. *** ## ProxyConfig Configures how HQ forwards API requests to Agents. It has the following fields: | Name | Required | Default | Type | Description | | ------------------- | -------- | ------- | -------- | --------------------------------------------------- | | `apiRequestTimeout` | No | `30s` | `string` | How long HQ waits for an Agent to answer a request. | ### ProxyConfig: apiRequestTimeout How long HQ waits for an Agent to answer an API request before giving up. Streaming connections, such as WebSockets, are not subject to this timeout; requests for an Agent's UI assets use a fixed 10 second timeout instead. It also applies to GetKafkaTopicRecords: HQ tells the Agent to stop slightly earlier, and returns the records read so far as a truncated response that clients continue via next\_offset. The duration follows the Go time.Duration format (e.g., "10s", "1m") and must be positive. Optional. If not set, it will default to `30s`. *** ## FeaturesConfig Toggles optional product features. It has the following fields: | Name | Required | Default | Type | Description | | ----------- | -------- | ------- | --------- | --------------------------- | | `launchPad` | No | `true` | `boolean` | Enables the Launch Pad tab. | ### FeaturesConfig: launchPad Controls whether the Launch Pad tab is available in Studio. When disabled, it is hidden for every user in the organisation. Optional. If not set, it will default to `true`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.lenses.io/latest/deployment/configuration/hq/configuration-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.