Configuration
Coroot can be configured using command-line arguments, environment variables, and a configuration file.
Configuration values are evaluated in the following precedence, with items higher on the list taking priority:
- Command-line arguments
- Environment variables
- Configuration file parameters
info
Certain configuration values can only be set through command-line flags, while others are available only via configuration file.
For instance, the projects parameter (a list of predefined projects) can only be configured via configuration file.
Command-line flags
| Argument | Environment Variable | Default Value | Description |
|---|---|---|---|
| --config | CONFIG | 0.0.0.0:8080 | Configuration file. |
| --listen | LISTEN | 0.0.0.0:8080 | Listen address in the format ip:port or :port. |
| --https-listen | HTTPS_LISTEN | HTTPS listen address in the format ip:port or :port. | |
| --http-disabled | HTTP_DISABLED | false | Disable plain HTTP server. |
| --grpc-disabled | GRPC_DISABLED | false | Disable gRPC server. |
| --grpc-listen | GRPC_LISTEN | :4317 | gRPC listen address - ip:port or :port. |
| --tls-cert-file | TLS_CERT_FILE | Path to the TLS certificate file. | |
| --tls-key-file | TLS_KEY_FILE | Path to the TLS private key file. | |
| --url-base-path | URL_BASE_PATH | / | Base URL to run Coroot at a sub-path, e.g., /coroot/. |
| --data-dir | DATA_DIR | /data | Path to the data directory. |
| --cache-ttl | CACHE_TTL | 30d | Metric Cache Time-To-Live (TTL). |
| --cache-gc-interval | CACHE_GC_INTERVAL | 10m | Metric Cache Garbage Collection (GC) interval. |
| --traces-ttl | TRACES_TTL | 7d | Traces Time-To-Live (TTL). |
| --logs-ttl | LOGS_TTL | 7d | Logs Time-To-Live (TTL). |
| --profiles-ttl | PROFILES_TTL | 7d | Profiles Time-To-Live (TTL). |
| --metrics-ttl | METRICS_TTL | 7d | Metrics Time-To-Live (TTL). |
| --pg-connection-string | PG_CONNECTION_STRING | PostgreSQL connection string (uses SQLite if not set). | |
| --disable-usage-statistics | DISABLE_USAGE_STATISTICS | false | Disable usage statistics. |
| --read-only | READ_ONLY | false | Enable read-only mode where configuration changes don't take effect. |
| --do-not-check-slo | DO_NOT_CHECK_SLO | false | Do not check Service Level Objective (SLO) compliance. |
| --do-not-check-for-deployments | DO_NOT_CHECK_FOR_DEPLOYMENTS | false | Do not check for new deployments. |
| --do-not-check-for-updates | DO_NOT_CHECK_FOR_UPDATES | false | Do not check for new versions. |
| --disable-builtin-alerts | DISABLE_BUILTIN_ALERTS | false | Disable all built-in alerting rules for all projects on startup. |
| --auth-anonymous-role | AUTH_ANONYMOUS_ROLE | Disable authentication and assign one of the following roles to the anonymous user: Admin, Editor, or Viewer. | |
| --auth-bootstrap-admin-password | AUTH_BOOTSTRAP_ADMIN_PASSWORD | Password for the default Admin user. | |
| --license-key | LICENSE_KEY | License key for Coroot Enterprise Edition. | |
| --global-clickhouse-address | GLOBAL_CLICKHOUSE_ADDRESS | The address of the ClickHouse server to be used for all projects. | |
| --global-clickhouse-user | GLOBAL_CLICKHOUSE_USER | The username for the ClickHouse server to be used for all projects. | |
| --global-clickhouse-password | GLOBAL_CLICKHOUSE_PASSWORD | The password for the ClickHouse server to be used for all projects. | |
| --global-clickhouse-initial-database | GLOBAL_CLICKHOUSE_INITIAL_DATABASE | The initial database on the ClickHouse server to be used for all projects. Coroot will automatically create and manage a dedicated database for each project within the server. | |
| --global-clickhouse-tls-enabled | GLOBAL_CLICKHOUSE_TLS_ENABLED | false | Whether TLS is enabled for the ClickHouse server connection (true or false). |
| --global-clickhouse-tls-skip-verify | GLOBAL_CLICKHOUSE_TLS_SKIP_VERIFY | false | Whether to skip verification of the ClickHouse server's TLS certificate (true or false). |
| --global-prometheus-url | GLOBAL_PROMETHEUS_URL | The URL of the Prometheus server to be used for all projects. | |
| --global-prometheus-tls-skip-verify | GLOBAL_PROMETHEUS_TLS_SKIP_VERIFY | false | Whether to skip verification of the Prometheus server's TLS certificate (true or false). |
| --global-refresh-interval | GLOBAL_REFRESH_INTERVAL | 15s | The interval for refreshing Prometheus data. |
| --global-prometheus-user | GLOBAL_PROMETHEUS_USER | The username for the Prometheus server to be used for all projects. | |
| --global-prometheus-password | GLOBAL_PROMETHEUS_PASSWORD | The password for the Prometheus server to be used for all projects. | |
| --global-prometheus-custom-headers | GLOBAL_PROMETHEUS_CUSTOM_HEADERS | Custom headers to include in requests to the Prometheus server. | |
| --global-prometheus-remote-write-url | GLOBAL_PROMETHEUS_REMOTE_WRITE_URL | The URL for metric ingestion though the Prometheus Remote Write protocol. | |
| --global-prometheus-use-clickhouse | GLOBAL_PROMETHEUS_USE_CLICKHOUSE | false | Use ClickHouse for metrics storage instead of Prometheus. When enabled, ClickHouse becomes the primary metrics backend. |
| --disable-clickhouse-space-manager | CLICKHOUSE_SPACE_MANAGER_DISABLED | false | Disable ClickHouse space manager that automatically cleans up old partitions. |
| --clickhouse-space-manager-usage-threshold | CLICKHOUSE_SPACE_MANAGER_USAGE_THRESHOLD | 70 | Disk usage percentage threshold for triggering partition cleanup in ClickHouse. |
| --clickhouse-space-manager-min-partitions | CLICKHOUSE_SPACE_MANAGER_MIN_PARTITIONS | 1 | Minimum number of partitions to keep when cleaning up ClickHouse disk space. |
Configuration file
Use the --config flag to specify the configuration file to load. The file must be in YAML format.
listen_address: 0.0.0.0:8080 # Listen address in the format `ip:port` or `:port`.
https_listen_address: # HTTPS listen address in the format `ip:port` or `:port`.
http_disabled: false # Disable plain HTTP server (default: false).
url_base_path: / # Base URL to run Coroot at a sub-path, e.g., `/coroot/`.
data_dir: /data # Path to the data directory.
# gRPC server configuration for receiving OTel traces and logs.
grpc:
disabled: false # Disable the gRPC server (default: false).
listenAddress: :4317 # Address to listen on for gRPC connections (default: :4317).
# TLS configuration for secure connections (enables TLS for gRPC server if defined).
tls:
certFile: # Path to the TLS certificate file.
keyFile: # Path to the TLS private key file.
cache:
ttl: 30d # Metric Cache Time-To-Live (TTL).
gc_interval: 10m # Metric Cache Garbage Collection (GC) interval.
# Coroot stores Traces, Logs, and Profiles in ClickHouse.
# Their retention is managed by setting a Time-To-Live (TTL) for the corresponding Clickhouse tables.
# The TTLs below are applied during table creation and do not currently affect existing tables.
traces:
ttl: 7d
logs:
ttl: 7d
profiles:
ttl: 7d
postgres: # Store configuration in a Postgres DB instead of SQLite
# URI form: "postgres://coroot:password@127.0.0.1:5432/coroot?sslmode=disable"
# KV form: "host=127.0.0.1 user=coroot password=password port=5432 dbname=coroot ssl_mode=disable"
# https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING
connection_string:
global_prometheus: # The Prometheus server to be used for all projects.
url: # http(s)://IP:Port/ or http(s)://Domain:Port/
refresh_interval: 15s # The interval for refreshing Prometheus data.
tls_skip_verify: false # Whether to skip verification of the Prometheus server's TLS certificate.
user: # The basic-auth username.
password: # The basic-auth password.
custom_headers: # Custom headers to include in requests to the Prometheus server.
# header_name: header_value
remote_write_url: # The URL for metric ingestion though the Prometheus Remote Write protocol.
use_clickhouse: false # Use ClickHouse for metrics storage instead of Prometheus.
global_clickhouse: # The ClickHouse server to be used for all projects.
address: # IP:Port or Domain:Port.
user: # The username for the ClickHouse server.
password: # The password for the ClickHouse server.
database: # The initial database on the ClickHouse server.
tls_enable: false # Whether TLS is enabled for the ClickHouse server connection.
tls_skip_verify: false # Whether to skip verification of the ClickHouse server's TLS certificate.
clickhouse_space_manager: # Automatically manage ClickHouse disk space by cleaning up old partitions.
enabled: true # Enable space manager (default: true).
usage_threshold_percent: 70 # Disk usage percentage threshold for triggering cleanup (default: 70).
min_partitions: 1 # Minimum number of partitions to keep per table (default: 1).
auth:
anonymous_role: # Disables authentication if set (one of Admin, Editor, or Viewer).
bootstrap_admin_password: # Password for the default Admin user.
do_not_check_for_deployments: false # Do not check for new deployments.
do_not_check_for_updates: false # Do not check for new versions.
disable_usage_statistics: false # Disable anonymous usage statistics.
disableBuiltinAlerts: false # Disable all built-in alerting rules for all projects on startup.
license_key: # License key for Coroot Enterprise Edition.
# The project defined here will be created if it does not exist
# and will be configured with the provided API keys.
# If a project with the same name already exists (e.g., configured via the UI),
# its API keys and other settings will be replaced.
# If remoteCoroot is set, Coroot uses the remote instance for metrics and ClickHouse access.
projects: # Create or update projects (configuration file only).
- name: # Project name (e.g., production, staging; must be unique; required).
memberProjects: # Optional list of existing project names to aggregate (multi-cluster mode).
- prod-eu
- prod-us
# Project API keys, used by agents to send telemetry data (required unless remoteCoroot is set).
apiKeys:
- key: # Random string or UUID (must be unique; required).
description: # The API key description (optional).
# Use another Coroot instance as the data source for this project.
remoteCoroot:
url: https://coroot.example.com # Base URL of the remote Coroot instance.
apiKey: # API key of the remote project (required).
tlsSkipVerify: false # Whether to skip TLS verification (default: false).
metricResolution: 15s # Prometheus query resolution/refresh interval (required).
# Project notification integrations.
notificationIntegrations:
baseURL: # The URL of Coroot instance (required). Used for generating links in notifications.
slack:
token: # Slack Bot User OAuth Token (required).
defaultChannel: # Default channel (required).
incidents: false # Notify of incidents (SLO violations).
deployments: false # Notify of deployments.
alerts: false # Notify of alerts.
teams:
webhookURL: # Microsoft Teams Webhook URL (required).
incidents: false # Notify of incidents (SLO violations).
deployments: false # Notify of deployments.
alerts: false # Notify of alerts.
pagerduty:
integrationKey: # PagerDuty Integration Key (required).
incidents: false # Notify of incidents (SLO violations).
alerts: false # Notify of alerts.
opsgenie:
apiKey: # Opsgenie API Key (required).
euInstance: false # EU instance of Opsgenie.
incidents: false # Notify of incidents (SLO violations).
alerts: false # Notify of alerts.
webhook:
url: # Webhook URL (required).
tlsSkipVerify: false # Whether to skip verification of the Webhook server's TLS certificate.
basicAuth: # Basic auth credentials.
username:
password:
customHeaders: # Custom headers to include in requests.
- key:
value:
customFields: # Static key-value pairs included as top-level fields in template data.
environment: production
team: platform
incidents: false # Notify of incidents (SLO violations).
deployments: false # Notify of deployments.
alerts: false # Notify of alerts.
incidentTemplate: "" # Incident template (required if `incidents: true`).
deploymentTemplate: "" # Deployment template (required if `deployments: true`).
alertTemplate: "" # Alert template (required if `alerts: true`).
# Project application category settings.
applicationCategories:
- name: # Application category name (required).
customPatterns: # List of glob patterns in the <namespace>/<application_name> format.
- staging/*
- test-*/*
notificationSettings: # Category notification settings.
incidents: # Notify of incidents (SLO violations).
enabled: true
slack:
enabled: true
channel: ops
teams:
enabled: false
pagerduty:
enabled: false
opsgenie:
enabled: false
webhook:
enabled: false
deployments: # Notify of deployments.
enabled: true
slack:
enabled: true
channel: general
teams:
enabled: false
webhook:
enabled: false
alerts: # Notify of alerts.
enabled: true
slack:
enabled: true
channel: alerts
teams:
enabled: false
pagerduty:
enabled: false
opsgenie:
enabled: false
webhook:
enabled: false
# Project custom applications settings.
customApplications:
- name: custom-app
instancePatterns:
- app@node1
- app@node2
# Alerting rules: adjust built-in rules or define custom ones.
# Rules defined here become read-only in the UI.
# For built-in rules, only the fields you specify are overridden; unset fields keep their current values.
# For custom rules, all required fields (name, source) must be provided.
alertingRules:
# Adjust a built-in rule (only override severity and description)
- id: storage-space # Required. Built-in rule ID or a custom ID you choose.
severity: critical
templates:
description: "Disk space critically low"
# Disable a built-in rule
- id: memory-pressure
enabled: false
# Custom check-based rule
- id: custom-postgres-latency
name: "Postgres latency (production)"
source:
type: check # One of: check, log_patterns, kubernetes_events, promql.
check:
checkId: postgres_latency
selector:
type: category # One of: all, category, applications.
categories:
- production
severity: critical # One of: warning, critical.
for: 5m
keepFiringFor: 5m
templates:
description: "Postgres latency is critically high in production."
enabled: true
# Custom PromQL-based rule
- id: custom-uptime
name: "Instance uptime"
source:
type: promql
promql:
expression: "up == 0"
severity: warning
templates:
summary: "Instance {{.instance}} is down"
# Custom log-based rule
- id: custom-log-errors
name: "Critical log errors"
source:
type: log_patterns
logPattern:
severities:
- error
- fatal
minCount: 5
maxAlertsPerApp: 10
evaluateWithAi: true
severity: critical
# Custom Kubernetes events-based rule
- id: custom-k8s-events
name: "K8s events (production)"
source:
type: kubernetes_events
kubernetesEvents:
minCount: 1
maxAlertsPerApp: 10
evaluateWithAi: true
selector:
type: category
categories:
- production
severity: warning
# Project inspection overrides
inspectionOverrides:
# applicationId format: <namespace>:<kind>:<name>
# namespace = `external` for external services, `_` for non-Kubernetes apps
sloLatency:
- applicationId: external:ExternalService:api.github.com:443
objectivePercent: 99
objectiveThreshold: 2s
- applicationId: default:Deployment:catalog
objectivePercent: 99.9
objectiveThreshold: 100ms
sloAvailability:
- applicationId: default:Deployment:catalog
objectivePercent: 98
# Single Sign-on configuration (Coroot Enterprise edition only).
# Choose either SAML or OIDC as the provider.
sso:
enabled: false
provider: saml # SSO provider: "saml" or "oidc".
defaultRole: Viewer # Default role for authenticated users (Admin, Editor, Viewer, or a custom role).
# SAML configuration (required if provider is "saml").
saml:
# SAML Identity Provider Metadata XML (required).
metadata: |
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://www.okta.com/exkk72*********n5d7">
...
</md:EntityDescriptor>
# OIDC configuration (required if provider is "oidc").
oidc:
issuerURL: https://accounts.google.com # OIDC provider issuer URL (required).
clientID: your-client-id # OAuth client ID (required).
clientSecret: your-client-secret # OAuth client secret (required).
# AI configuration (Coroot Enterprise edition only).
ai:
provider: # AI model provider (one of: anthropic, openai, or openai_compatible).
anthropic:
apiKey: # Anthropic API key.
openai:
apiKey: # OpenAI API key.
openaiCompatible:
apiKey: # API key.
baseUrl: # Base URL (e.g., https://generativelanguage.googleapis.com/v1beta/openai).
model: # Model name (e.g., gemini-2.5-pro-preview-06-05).
# Coroot Cloud integration.
corootCloud:
# API key (required). Can be obtained from the UI after connecting to Coroot Cloud.
apiKey:
# Root Cause Analysis (RCA) configuration.
rca:
# If true, incidents will not be investigated automatically.
disableIncidentsAutoInvestigation: false
Looking for 24/7 support from the Coroot team? Subscribe to Coroot Enterprise:Start free trial