Pyroscope Server Configuration

There are 3 ways to configure pyroscope. Configuration precedence is evaluated in the following order:

• command line arguments
• environment variables
• config files

Command line arguments

This is the easiest way to configure pyroscope. For the list of command line arguments and default values, run pyroscope server -help:

Name	Default Value	Usage
adhoc-data-path	OS dependent	Directory where pyroscope stores adhoc profiles.
analytics-opt-out	false	Disables analytics.
log-level	info	Log level: debug|info|warn|error.
badger-log-level	error	Log level: debug|info|warn|error.
storage-path	/var/lib/pyroscope	Directory where pyroscope stores profiling data.
api-bind-addr	:4040	Port for the HTTP server used for data ingestion and web UI.
base-url		Base URL for when the server is behind a reverse proxy with a different path.
cache-evict-threshold	0.25	Percentage of memory at which cache evictions start.
cache-evict-volume	0.33	Percentage of cache that is evicted per eviction run.
badger-no-truncate	false	Indicates whether value log files should be truncated to delete corrupt data, if any.
disable-pprof-endpoint	false	Disables /debug/pprof route.
max-nodes-serialization	2048	Max number of nodes used when saving profiles to disk.
max-nodes-render	8192	Max number of nodes used to display data on the frontend.
no-adhoc-ui	false	Disable the adhoc UI interface.
hide-applications	[]	Please don't use, this will soon be deprecated.
retention	0s	Sets the maximum amount of time the profiling data is stored for. Data before this threshold is deleted. Disabled by default.
exemplars-retention	0s	Sets the maximum amount of time profile exemplars are stored for. Data before this threshold is deleted. Disabled by default.
retention-levels	{}	Specifies how long the profiling data is stored per aggregation level. Disabled by default.
tls-certificate-file	""	Location of TLS Certificate file (.crt).
tls-key-file	""	Location of TLS Private key file (.key).

Environment variables

Environment variables MUST have PYROSCOPE_ prefix and be in UPPER_SNAKE_CASE format, for example:

PYROSCOPE_API_BIND_ADDR=:9999 pyroscope server

Configuration file

Config files are stored in YAML format. The default configuration file path is located at:

• /etc/pyroscope/server.yml on Linux
• /usr/local/etc/pyroscope/server.yml on Intel macOS
• /opt/homebrew/etc/pyroscope/server.yml on M1 macOS

You can override the location with -config <path> argument, for example:

pyroscope server -config my-custom-config.yml

Or an environment variable:

PYROSCOPE_CONFIG=/tmp/pyroscope-server.yml pyroscope server

---# Disables analytics.analytics-opt-out: "false"
# Log level: debug|info|warn|error.log-level: "info"
# Log level: debug|info|warn|error.badger-log-level: "error"
# Directory where pyroscope stores profiling data.storage-path: "/var/lib/pyroscope"
# Port for the HTTP server used for data ingestion and web UI.api-bind-addr: ":4040"
# Base URL for when the server is behind a reverse proxy with a different path.base-url: ""
# Percentage of memory at which cache evictions start.cache-evict-threshold: "0.25"
# Percentage of cache that is evicted per eviction run.cache-evict-volume: "0.33"
# Database configuration. By default, Pyroscope Server uses embedded sqlite3 database.database:  # Indicates the database type. Supported DB engines: sqlite3.  type: "sqlite3"  # Database connection string. Specific to the engine.  url: "/var/lib/pyroscope/pyroscope.db"
# Indicates whether value log files should be truncated to delete corrupt data, if any.badger-no-truncate: "false"
# Disables /debug/pprof route.disable-pprof-endpoint: "false"
# Max number of nodes used when saving profiles to disk.max-nodes-serialization: "2048"
# Max number of nodes used to display data on the frontend.max-nodes-render: "8192"
# Please don't use, this will soon be deprecated.hide-applications: []
# Sets the maximum amount of time the profiling data is stored for. Data before this threshold is deleted. Disabled by default.retention: "0s"
# Sets the maximum amount of time profile exemplars are stored for. Data before this threshold is deleted. Disabled by default.exemplars-retention: "0s"
# Specifies how long the profiling data is stored per aggregation level. Disabled by default.retention-levels: {}# 0: 720h  # 30 days# 1: 2160h # 90 days
# Metrics export rules.metrics-export-rules: {}
# A list of scrape configurations.scrape-configs: []
# Location of TLS Certificate file (.crt).tls-certificate-file: ""
# Location of TLS Private key file (.key).tls-key-file: ""

Authentication

See the server authentication page for more details on how to add authentication to your Pyroscope server.

Data retention

See the data retention page for more details on how to configure retention policies.

Metrics export rules

See the metrics export page for more details on how to export profiling data as Prometheus metrics.

Scraping

See the pull mode page for more details on how to configure remote targets scraping.