> ## Documentation Index
> Fetch the complete documentation index at: https://proxy-docs.permify.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration
Permify offers various options for configuring your Permify Server. Here is the example configuration YAML file with glossary below.
You can also find
this [example config file](https://github.com/Permify/permify/blob/master/example.config.yaml) in Permify repo.
### Configure Using Flags
Alternatively, you can set configuration options using flags when running the command. See all the configuration flags by running,
```shell theme={null}
docker run -p 3476:3476 -p 3478:3478 ghcr.io/permify/permify --help
```
### Configuration Using YAML File
```yaml theme={null}
# The server section specifies the HTTP and gRPC server settings,
# including whether or not TLS is enabled and the certificate and
# key file locations.
server:
host: ""
rate_limit: 100
http:
enabled: true
port: 3476
grpc_target_host: 127.0.0.1
tls:
enabled: true
cert: /etc/letsencrypt/live/yourdomain.com/fullchain.pem
key: /etc/letsencrypt/live/yourdomain.com/privkey.pem
grpc:
port: 3478
tls:
enabled: true
cert: /etc/letsencrypt/live/yourdomain.com/fullchain.pem
key: /etc/letsencrypt/live/yourdomain.com/privkey.pem
# The logger section sets the logging level for the service.
logger:
level: info
# The profiler section enables or disables the pprof profiler and
# sets the port number for the profiler endpoint.
profiler:
enabled: true
port: 6060
# The authn section specifies the authentication method for the service.
authn:
enabled: true
method: preshared
preshared:
keys: [ ]
# The tracer section enables or disables distributed tracing and sets the
# exporter and endpoint for the tracing data.
tracer:
exporter: zipkin
endpoint: http://localhost:9411/api/v2/spans
enabled: true
# The meter section enables or disables metrics collection and sets the
# exporter and endpoint for the collected metrics.
meter:
exporter: otlp
endpoint: localhost:4318
enabled: true
# The service section sets various service-level settings, including whether
# or not to use a circuit breaker, and cache sizes for schema, permission,
# and relationship data.
service:
circuit_breaker: false
watch:
enabled: false
schema:
cache:
number_of_counters: 1_000
max_cost: 10MiB
permission:
bulk_limit: 100
concurrency_limit: 100
cache:
number_of_counters: 10_000
max_cost: 10MiB
# The database section specifies the database engine and connection settings,
# including the URI for the database, whether or not to auto-migrate the database,
# and connection pool settings.
database:
engine: postgres
uri: postgres://user:password@host:5432/db_name
auto_migrate: false
max_connections: 20 # Maximum number of connections in the pool (maps to pgxpool MaxConns)
max_open_connections: 20 # Deprecated: use max_connections instead. Kept for backward compatibility.
max_idle_connections: 1 # Deprecated: use min_connections instead. Kept for backward compatibility (maps to MinConnections if min_connections is not set).
min_connections: 0 # Minimum number of connections in the pool (maps to pgxpool MinConns). If 0 and max_idle_connections is set, max_idle_connections will be used.
min_idle_connections: 0 # Minimum idle connections (maps to pgxpool MinIdleConns). Must be explicitly set if needed (not set in old code).
max_connection_lifetime: 300s
max_connection_idle_time: 60s
health_check_period: 0s # Use pgxpool default (1 minute) if 0
max_connection_lifetime_jitter: 0s # Will default to 20% of max_connection_lifetime if 0
connect_timeout: 0s # Use pgx default (no timeout) if 0
garbage_collection:
enabled: true
interval: 200h
window: 200h
timeout: 5m
# distributed configuration settings
distributed:
# Indicates whether the distributed mode is enabled or not
enabled: true
# The address of the distributed service.
# Using a Kubernetes DNS name suggests this service runs in a Kubernetes cluster
# under the 'default' namespace and is named 'permify'
address: "kubernetes:///permify.default"
# The port on which the service is exposed
port: "5000"
```
## Configuration Glossary
#### Definition
Server options to run Permify. (`grpc` and `http` available for now.)
#### Structure
```
├── server
├── host
├── rate_limit
├── (`grpc` or `http`)
│ ├── enabled
│ ├── port
│ ├── grpc_target_host
│ └── tls
│ ├── enabled
│ ├── cert
│ └── key
```
#### Glossary
| Required | Argument | Default | Description |
| -------- | ------------------------- | --------- | ------------------------------------------------------------------- |
| \[ ] | host | "" | host/interface to bind the HTTP server. |
| \[ ] | rate\_limit | 100 | the maximum number of requests the server should handle per second. |
| \[x] | \[ server\_type ] | - | server option type can either be `grpc` or `http`. |
| \[ ] | enabled (for server type) | true | switch option for server. |
| \[x] | port | - | port that server run on. |
| \[ ] | grpc\_target\_host (HTTP) | 127.0.0.1 | host the HTTP gateway uses to connect to the local gRPC server. |
| \[x] | tls | - | transport layer security options. |
| \[ ] | enabled (for tls) | false | switch option for tls |
| \[ ] | cert | - | tls certificate path. |
| \[ ] | key | - | tls key path |
#### ENV
| Argument | ENV | Type |
| ------------------------- | ------------------------------------- | ------------ |
| server-host | PERMIFY\_SERVER\_HOST | string |
| rate\_limit | PERMIFY\_RATE\_LIMIT | int |
| grpc-port | PERMIFY\_GRPC\_PORT | string |
| grpc-tls-enabled | PERMIFY\_GRPC\_TLS\_ENABLED | boolean |
| grpc-tls-key-path | PERMIFY\_GRPC\_TLS\_KEY\_PATH | string |
| grpc-tls-cert-path | PERMIFY\_GRPC\_TLS\_CERT\_PATH | string |
| http-enabled | PERMIFY\_HTTP\_ENABLED | boolean |
| http-port | PERMIFY\_HTTP\_PORT | string |
| http-grpc-target-host | PERMIFY\_HTTP\_GRPC\_TARGET\_HOST | string |
| http-tls-key-path | PERMIFY\_HTTP\_TLS\_KEY\_PATH | string |
| http-tls-cert-path | PERMIFY\_HTTP\_TLS\_CERT\_PATH | string |
| http-cors-allowed-origins | PERMIFY\_HTTP\_CORS\_ALLOWED\_ORIGINS | string array |
| http-cors-allowed-headers | PERMIFY\_HTTP\_CORS\_ALLOWED\_HEADERS | string array |
#### Definition
Real time logs of authorization. Permify uses [zerolog] as a logger.
[zerolog]: https://github.com/rs/zerolog
#### Structure
```
├── logger
├── level
├── service_name
```
#### Glossary
| Required | Argument | Default | Description |
| -------- | ------------- | ------- | ------------------------------------------------------- |
| \[x] | level | info | logger levels: `error`, `warn`, `info` , `debug` |
| \[x] | output | text | logger output: `json`, `text` |
| \[ ] | service\_name | permify | Override the service name reported by the log exporter. |
#### ENV
| Argument | ENV | Type |
| ---------------- | --------------------------- | ------ |
| log-level | PERMIFY\_LOG\_LEVEL | string |
| log-output | PERMIFY\_LOG\_OUTPUT | string |
| log-service-name | PERMIFY\_LOG\_SERVICE\_NAME | string |
#### Definition
You can choose to authenticate users to interact with Permify API.
There are 2 authentication method you can choose:
* Pre Shared Keys
* OpenID Connect
#### Pre Shared Keys
On this method, you must provide a pre shared keys in order to identify yourself.
#### Structure
```
├── authn
| ├── method
| ├── enabled
| ├── preshared
| ├── keys
```
#### Glossary
| Required | Argument | Default | Description |
| -------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| \[x] | method | - | Authentication method can be either `oidc` or `preshared`. |
| \[ ] | enabled | true | switch option authentication config |
| \[x] | keys | - | Private key/keys for server authentication. Permify does not provide this key, so it must be generated by the users. |
#### ENV
| Argument | ENV | Type |
| -------------------- | ------------------------------- | ------------ |
| authn-enabled | PERMIFY\_AUTHN\_ENABLED | boolean |
| authn-method | PERMIFY\_AUTHN\_METHOD | string |
| authn-preshared-keys | PERMIFY\_AUTHN\_PRESHARED\_KEYS | string array |
#### OpenID Connect
Permify supports OpenID Connect (OIDC). OIDC provides an identity layer on top of OAuth 2.0 to address the shortcomings
of using OAuth 2.0 for establishing identity.
With this authentication method, you be able to integrate your existing Identity Provider (IDP) to validate JSON Web
Tokens (JWTs) using JSON Web Keys (JWKs). By doing so, only trusted tokens from the IDP will be accepted for
authentication.
#### Structure
```
├── authn
| ├── method
| ├── enabled
| ├── oidc
| ├── issuer
| ├── audience
| ├── refresh_interval
| ├── backoff_interval
| ├── backoff_frequency
| ├── backoff_max_retries
| ├── valid_methods
```
#### Glossary
| Required | Argument | Default | Description |
| -------- | --------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \[x] | method | - | Authentication method can be either `oidc` or `preshared`. |
| \[ ] | enabled | false | Switch option to enable or disable authentication config. |
| \[x] | audience | - | The audience identifies the intended recipients of the token, typically the API or resource server. It ensures tokens are used only by the authorized party. |
| \[x] | issuer | - | This is the URL of the provider that is responsible for authenticating users. You will use this URL to discover information about the provider in step 1 of the authentication process. |
| \[x] | refresh\_interval | 15m | The interval at which the authentication information should be refreshed to ensure that it remains valid and up-to-date. |
| \[x] | backoff\_interval | 12s | The delay between retries when attempting to authenticate if the key is not found. The system will retry at intervals, which may vary, to avoid constant retry attempts. |
| \[x] | backoff\_frequency | - | The duration to wait before retrying after a failed authentication attempt. This helps to manage the load on the authentication service by introducing a delay between retries, ensuring that repeated failures do not overwhelm the service or lead to excessive requests. This value should be configured according to the expected response times and reliability of the authentication provider. |
| \[x] | backoff\_max\_retries | 5 | The maximum number of retry attempts to make if key is not found. |
| \[x] | valid\_methods | \["RS256","HS256"] | A list of accepted signing methods for tokens. This ensures that only tokens signed using one of the specified algorithms will be considered valid. |
#### ENV
| Argument | ENV | Type |
| ------------------------------ | ---------------------------------------- | ------------ |
| authn-enabled | PERMIFY\_AUTHN\_ENABLED | boolean |
| authn-method | PERMIFY\_AUTHN\_METHOD | string |
| authn-oidc-issuer | PERMIFY\_AUTHN\_OIDC\_ISSUER | string |
| authn-oidc-audience | PERMIFY\_AUTHN\_OIDC\_AUDIENCE | string |
| authn-oidc-refresh-interval | PERMIFY\_AUTHN\_OIDC\_REFRESH\_INTERVAL | duration |
| authn-oidc-backoff-interval | PERMIFY\_AUTHN\_OIDC\_BACKOFF\_INTERVAL | duration |
| authn-oidc-backoff-frequency | PERMIFY\_AUTHN\_OIDC\_BACKOFF\_FREQUENCY | duration |
| authn-oidc-backoff-max-retries | PERMIFY\_AUTHN\_OIDC\_BACKOFF\_RETRIES | int |
| authn-oidc-valid-methods | PERMIFY\_AUTHN\_OIDC\_VALID\_METHODS | string array |
#### Definition
Permify integrated with [jaeger], [otlp], [signoz], and [zipkin] tacing tools to analyze performance and behavior of
your
authorization when using Permify.
#### Structure
```
├── tracer
| ├── exporter
| ├── endpoint
| ├── enabled
| ├── insecure
| ├── urlpath
| ├── service_name
```
#### Glossary
| Required | Argument | Default | Description |
| -------- | ------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| \[x] | exporter | - | Tracer exporter, the options are `jaeger`, `otlp`, `signoz`, and `zipkin`. |
| \[x] | endpoint | - | export uri for tracing data. |
| \[ ] | enabled | false | switch option for tracing. |
| \[ ] | urlpath | | allows one to override the default URL path for otlp, used for sending traces. If unset, default ("/v1/traces") will be used. |
| \[ ] | insecure | false | Whether to use HTTP instead of HTTPs for exporting the traces. |
| \[ ] | service\_name | permify | Override the service name reported by the tracing exporter. |
#### ENV
| Argument | ENV | Type |
| ------------------- | ------------------------------ | ------- |
| tracer-enabled | PERMIFY\_TRACER\_ENABLED | boolean |
| tracer-exporter | PERMIFY\_TRACER\_EXPORTER | string |
| tracer-endpoint | PERMIFY\_TRACER\_ENDPOINT | string |
| tracer-urlpath | PERMIFY\_TRACER\_URL\_PATH | string |
| tracer-insecure | PERMIFY\_TRACER\_INSECURE | boolean |
| tracer-service-name | PERMIFY\_TRACER\_SERVICE\_NAME | string |
#### Definition
Configuration for observing metrics; check count, cache check count and session information; Permify version, hostname,
os, arch.
#### Structure
```
├── meter
| ├── exporter
| ├── endpoint
| ├── enabled
| ├── insecure
| ├── urlpath
| ├── service_name
```
#### Glossary
| Required | Argument | Default | Description |
| -------- | ------------- | ------- | ------------------------------------------------------------ |
| \[x] | exporter | - | [otlp](https://opentelemetry.io/docs/collector/) is default. |
| \[x] | endpoint | - | export uri for metric observation |
| \[ ] | enabled | true | switch option for meter tracing. |
| \[ ] | service\_name | permify | Override the service name reported by the metrics exporter. |
#### ENV
| Argument | ENV | Type |
| ------------------ | ----------------------------- | ------- |
| meter-enabled | PERMIFY\_METER\_ENABLED | boolean |
| meter-exporter | PERMIFY\_METER\_EXPORTER | string |
| meter-endpoint | PERMIFY\_METER\_ENDPOINT | string |
| meter-urlpath | PERMIFY\_METER\_URL\_PATH | string |
| meter-insecure | PERMIFY\_METER\_INSECURE | boolean |
| meter-service-name | PERMIFY\_METER\_SERVICE\_NAME | string |
#### Definition
Configurations for the database that points out where your want to store your authorization data (relation tuples,
audits, decision logs, authorization model)
#### Structure
```
├── database
| ├── engine
| ├── uri
| ├── writer.uri
| ├── reader.uri
| ├── auto_migrate
| ├── max_connections
| ├── max_open_connections (deprecated)
| ├── max_idle_connections (deprecated)
| ├── min_connections
| ├── min_idle_connections
| ├── max_connection_lifetime
| ├── max_connection_idle_time
| ├── health_check_period
| ├── max_connection_lifetime_jitter
| ├── connect_timeout
| ├── max_data_per_write
| ├── max_retries
| ├── watch_buffer_size
| ├──garbage_collection
| ├──enable: true
| ├──interval: 3m
| ├──timeout: 3m
| ├──window: 720h
```
#### Glossary
| Required | Argument | Default | Description |
| -------- | ----------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \[x] | engine | memory | Data source. Permify supports **PostgreSQL**(`'postgres'`) for now. Contact with us for your preferred database. |
| \[x] | uri | - | Uri of your data source. |
| \[ ] | writer.uri | - | Writer uri of your data source. If not set, uses uri. |
| \[ ] | reader.uri | - | Reader uri of your data source. If not set, uses uri. |
| \[ ] | auto\_migrate | true | When its configured as false migrating flow won't work. |
| \[ ] | max\_connections | 0 | Maximum number of connections in the pool (maps to pgxpool MaxConns). 0 means unlimited (pgx default). If not set, max\_open\_connections will be used for backward compatibility. |
| \[ ] | max\_open\_connections (deprecated) | 20 | Deprecated: use max\_connections instead. Kept for backward compatibility. |
| \[ ] | max\_idle\_connections (deprecated) | 1 | Deprecated: use min\_connections instead. Kept for backward compatibility (maps to MinConnections if min\_connections is not set). |
| \[ ] | min\_connections | 0 | Minimum number of connections in the pool (maps to pgxpool MinConns). If 0 and max\_idle\_connections is set, max\_idle\_connections will be used. |
| \[ ] | min\_idle\_connections | 0 | Minimum number of idle connections in the pool (maps to pgxpool MinIdleConns). Must be explicitly set if needed (not set in old code). |
| \[ ] | max\_connection\_lifetime | 300s | Determines the maximum lifetime of a connection in seconds. |
| \[ ] | max\_connection\_idle\_time | 60s | Determines the maximum time in seconds that a connection can remain idle before it is closed. |
| \[ ] | health\_check\_period | 0s | Period between health checks on idle connections. 0 means use pgxpool default (1 minute). |
| \[ ] | max\_connection\_lifetime\_jitter | 0s | Jitter added to MaxConnLifetime to prevent all connections from expiring at once. 0 means default to 20% of max\_connection\_lifetime. |
| \[ ] | connect\_timeout | 0s | Maximum time to wait when establishing a new connection. 0 means use pgx default (no timeout). |
| \[ ] | max\_data\_per\_write | 1000 | Sets the maximum amount of data per write operation to the database. |
| \[ ] | max\_retries | 10 | Defines the maximum number of retries for database operations in case of failure. |
| \[ ] | watch\_buffer\_size | 100 | Specifies the buffer size for database watch operations, impacting how many changes can be queued. |
| \[ ] | enable (for garbage collection) | false | Switch option for garbage collection. |
| \[ ] | interval | 3m | Determines the run period of a Garbage Collection operation. |
| \[ ] | timeout | 3m | Sets the duration of the Garbage Collection timeout. |
| \[ ] | window | 720h | Determines how much backward cleaning the Garbage Collection process will perform. |
#### ENV
| Argument | ENV | Type |
| ------------------------------------------ | ---------------------------------------------------- | -------- |
| database-engine | PERMIFY\_DATABASE\_ENGINE | string |
| database-uri | PERMIFY\_DATABASE\_URI | string |
| database-writer-uri | PERMIFY\_DATABASE\_WRITER\_URI | string |
| database-reader-uri | PERMIFY\_DATABASE\_READER\_URI | string |
| database-auto-migrate | PERMIFY\_DATABASE\_AUTO\_MIGRATE | boolean |
| database-max-connections | PERMIFY\_DATABASE\_MAX\_CONNECTIONS | int |
| database-max-open-connections (deprecated) | PERMIFY\_DATABASE\_MAX\_OPEN\_CONNECTIONS | int |
| database-max-idle-connections (deprecated) | PERMIFY\_DATABASE\_MAX\_IDLE\_CONNECTIONS | int |
| database-min-connections | PERMIFY\_DATABASE\_MIN\_CONNECTIONS | int |
| database-min-idle-connections | PERMIFY\_DATABASE\_MIN\_IDLE\_CONNECTIONS | int |
| database-max-connection-lifetime | PERMIFY\_DATABASE\_MAX\_CONNECTION\_LIFETIME | duration |
| database-max-connection-idle-time | PERMIFY\_DATABASE\_MAX\_CONNECTION\_IDLE\_TIME | duration |
| database-health-check-period | PERMIFY\_DATABASE\_HEALTH\_CHECK\_PERIOD | duration |
| database-max-connection-lifetime-jitter | PERMIFY\_DATABASE\_MAX\_CONNECTION\_LIFETIME\_JITTER | duration |
| database-connect-timeout | PERMIFY\_DATABASE\_CONNECT\_TIMEOUT | duration |
| database-max-data-per-write | PERMIFY\_DATABASE\_MAX\_DATA\_PER\_WRITE | int |
| database-max-retries | PERMIFY\_DATABASE\_MAX\_RETRIES | int |
| database-watch-buffer-size | PERMIFY\_DATABASE\_WATCH\_BUFFER\_SIZE | int |
| database-garbage-collection-enabled | PERMIFY\_DATABASE\_GARBAGE\_COLLECTION\_ENABLED | boolean |
| database-garbage-collection-interval | PERMIFY\_DATABASE\_GARBAGE\_COLLECTION\_INTERVAL | duration |
| database-garbage-collection-timeout | PERMIFY\_DATABASE\_GARBAGE\_COLLECTION\_TIMEOUT | duration |
| database-garbage-collection-window | PERMIFY\_DATABASE\_GARBAGE\_COLLECTION\_WINDOW | duration |
#### Production Best Practices: Connection Pooling with pgcat
For production deployments, especially when running multiple Permify instances, we **strongly recommend** using **pgcat** (PostgreSQL Connection Pooler) for server-side connection pooling. This helps manage database connections efficiently and prevents connection exhaustion.
For detailed information about pgcat setup, configuration, and best practices, see the [Database Pooling with Pgcat](/setting-up/installation/pooling) guide.
**Why use pgcat?**
* **Connection Management**: pgcat manages a pool of connections to PostgreSQL, allowing multiple Permify instances to share connections efficiently
* **Performance**: Reduces connection overhead and improves query performance
**Configuration Example**
When using pgcat with session mode, configure Permify to connect through pgcat instead of directly to PostgreSQL:
```yaml theme={null}
database:
engine: postgres
writer:
uri: postgresql://postgres:password@pgcat:6432/permify?plan_cache_mode=force_custom_plan&default_query_exec_mode=cache_describe
reader:
uri: postgresql://postgres:password@pgcat:6432/permify?plan_cache_mode=force_custom_plan&default_query_exec_mode=cache_describe
max_connections: 1 # Keep low since pgcat handles pooling
min_connections: 0
min_idle_connections: 0
max_connection_lifetime: 300s
max_connection_idle_time: 60s
```
**Key Points:**
* Point your `uri`, `writer.uri`, and `reader.uri` to pgcat (typically on port `6432`) instead of PostgreSQL directly
* Set `max_connections` to a low value since pgcat manages the actual connection pool
* For session mode with pgcat, set `min_connections` to `0` to allow the pool to shrink when not needed
* Configure connection lifecycle settings to help with connection cycling and prevent connection exhaustion
#### Definition
Configurations for the permify service and how it should behave. You can configure the circuit breaker pattern,
configuration watcher, and service specific options for permission and schema services (rate limiting, concurrency
limiting, cache size).
#### Structure
```
├── service
| ├── circuit_breaker
| ├── watch:
| | ├── enabled
| ├── schema:
| | ├── cache:
| | | ├── number_of_counters
| | | ├── max_cost
| | permission:
| | | ├── bulk_limit
| | | ├── concurrency_limit
| | | ├── cache:
| | | | ├── number_of_counters
| | | | ├── max_cost
```
#### Glossary
| Required | Argument | Default | Description |
| -------- | --------------------------------- | ------- | ------------------------------------------------- |
| \[ ] | circuit\_breaker | false | switch option to use the circuit breaker pattern. |
| \[ ] | watch | false | switch option for configuration watcher. |
| \[ ] | schema.cache.number\_of\_counters | 1\_000 | number of counters for schema service. |
| \[ ] | schema.cache.max\_cost | 10MiB | max cost for schema cache. |
| \[ ] | permission.bulk\_limit | 100 | bulk operations limit for permission service. |
| \[ ] | permission.concurrency\_limit | 100 | concurrency limit for permission service. |
| \[ ] | permission.cache.max\_cost | 10MiB | max cost for permission service. |
#### ENV
| Argument | ENV | Type |
| --------------------------------------- | ----------------------------------------------------- | ------- |
| service-circuit-breaker | PERMIFY\_SERVICE\_CIRCUIT\_BREAKER | boolean |
| service-watch-enabled | PERMIFY\_SERVICE\_WATCH\_ENABLED | boolean |
| service-schema-cache-number-of-counters | PERMIFY\_SERVICE\_SCHEMA\_CACHE\_NUMBER\_OF\_COUNTERS | int |
| service-schema-cache-max-cost | PERMIFY\_SERVICE\_SCHEMA\_CACHE\_MAX\_COST | int |
| service-permission-bulk-limit | PERMIFY\_SERVICE\_PERMISSION\_BULK\_LIMIT | int |
| service-permission-concurrency-limit | PERMIFY\_SERVICE\_PERMISSION\_CONCURRENCY\_LIMIT | int |
| service-permission-cache-max-cost | PERMIFY\_SERVICE\_PERMISSION\_CACHE\_MAX\_COST | int |
#### Definition
pprof is a performance profiler for Go programs. It allows developers to analyze and understand the performance
characteristics of their code by generating detailed profiles of program execution
When enabled, Permify exposes Go's standard pprof HTTP endpoints on the configured port (default `6060`):
| Endpoint | Purpose |
| ------------------------------------- | ------------------------------------------------------------------------------------- |
| `GET /debug/pprof/profile?seconds=30` | CPU profile — shows which functions are consuming CPU cycles over the sampling window |
| `GET /debug/pprof/trace?seconds=5` | Execution trace — records goroutine scheduling, GC, and syscall events |
| `GET /debug/pprof/heap` | Heap allocation snapshot — identifies memory-heavy code paths |
| `GET /debug/pprof/goroutine` | List all goroutines and their stack traces — useful for detecting goroutine leaks |
| `GET /debug/pprof/` | Index of all available profiles |
You can analyse captured profiles locally using Go's built-in tooling:
```bash theme={null}
# Download and open a 30-second CPU profile in the interactive UI
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30
```
**When to enable the profiler:**
* Investigating a CPU spike or unexpectedly high latency in Permify.
* During load or capacity testing to identify bottlenecks before production.
* When suspecting a performance regression after a version upgrade.
**Best practice:** Enable the profiler **temporarily** when needed, then disable it again. Keeping it permanently open in production is not recommended — it exposes an unauthenticated HTTP endpoint and adds a small constant overhead.
The pprof endpoint has no built-in authentication. Restrict network access to it (e.g. via a sidecar, internal network policy, or firewall rule) so it is not reachable from the public internet.
#### Structure
```
├── profiler
| ├── enabled
| ├── port
```
#### Glossary
| Required | Argument | Default | Description |
| -------- | -------- | ------- | --------------------------------------------- |
| \[ ] | enabled | true | switch option for profiler. |
| \[x] | port | - | port that profiler runs on *(default: 6060)*. |
#### ENV
| Argument | ENV | Type |
| ---------------- | -------------------------- | ------- |
| profiler-enabled | PERMIFY\_PROFILER\_ENABLED | boolean |
| profiler-port | PERMIFY\_PROFILER\_PORT | string |
#### Definition
A consistent hashing ring ensures data distribution that minimizes reorganization when nodes are added or removed,
improving scalability and performance in distributed systems."
#### Structure
```
├── distributed
| ├── enabled
| ├── address
| ├── port
```
#### Glossary
| Required | Argument | Default | Description |
| -------- | -------- | ------- | ------------------------------------ |
| \[x] | enabled | false | switch option for distributed. |
| \[] | address | - | address of the distributed service |
| \[] | port | 5000 | port on which the service is exposed |
#### ENV
| Argument | ENV | Type |
| ------------------- | ----------------------------- | ------- |
| distributed-enabled | PERMIFY\_DISTRIBUTED\_ENABLED | boolean |
| distributed-address | PERMIFY\_DISTRIBUTED\_ADDRESS | string |
| distributed-port | PERMIFY\_DISTRIBUTED\_PORT | string |
[jaeger]: https://www.jaegertracing.io/
[otlp]: https://opentelemetry.io/
[zipkin]: https://zipkin.io/
[signoz]: https://signoz.io/