Configuration reference
Every environment variable, its default, and the parts of config/sailfish.php that have none.
Sailfish works with no configuration on an application that watches its own database. Everything it reads is set by environment variables with the defaults below, and Redis and the cache stay off until you name a connection. Detector thresholds, notification types, retention, cache groups and hidden settings have no environment variable; change them in the published config:
php artisan vendor:publish --tag=sailfish-config
Environment variables#
| Variable | Default | What it does |
|---|---|---|
SAILFISH_ENABLED | true | Master switch. When false Sailfish registers no commands, no schedule and no dashboard. Its migrations still load. |
SAILFISH_DB_CONNECTION | app default | Read performance_schema from here, and store the sailfish_* tables here |
SAILFISH_SCHEMAS | the connection's database | Comma-separated databases whose tables, indexes and statements are recorded |
SAILFISH_DIGEST_LIMIT | 1000 | Most statement digests read per collection |
SAILFISH_SCHEDULE_ENABLED | true | Put the commands on the scheduler. False to schedule them yourself. |
SAILFISH_PATH | sailfish | Where the dashboard is served |
SAILFISH_DOMAIN | none | Serve the dashboard on this domain only |
SAILFISH_NOTIFY_CHANNELS | none | Comma-separated: mail, slack, webhook |
SAILFISH_NOTIFY_MAIL | none | Comma-separated addresses |
SAILFISH_SLACK_WEBHOOK_URL | none | An incoming webhook, or a #channel to post to through the bot token |
SAILFISH_WEBHOOK_URL | none | Where the webhook channel POSTs JSON |
SAILFISH_NOTIFY_REPEAT_MINUTES | 360 | Send an immediate event again while it stays open this long. 0 never repeats. |
SAILFISH_DAILY_DIGEST_AT | 09:00 | When the daily digest goes out |
SAILFISH_ROLLUP_AT | 03:00 | When sailfish:rollup runs |
SAILFISH_LONG_TRANSACTION_SECONDS | 5 | Keep each finished transaction that ran at least this long (see transactions) |
SAILFISH_REDIS_CONNECTION | none | One of the application's Redis connections to read INFO from as well (see Redis) |
SAILFISH_REDIS_TIMEOUT | 2 | Seconds to wait for Redis to connect or answer before recording it as unread |
SAILFISH_CACHE_ENABLED | false | Count what the application does with its cache, for each group of keys (see cache) |
SAILFISH_CACHE_REDIS_CONNECTION | SAILFISH_REDIS_CONNECTION | The Redis connection the application's processes leave those counts in until a collection takes them |
SAILFISH_CACHE_KEY_DEPTH | 1 | How many :-separated segments of a key name its group |
Connection and schemas#
Sailfish uses one connection for both jobs. Leaving SAILFISH_DB_CONNECTION empty uses the application's
default, and leaving SAILFISH_SCHEMAS empty watches the database that connection points at, which is
the right answer for an application watching itself.
To keep the performance_schema grant off your application's user, define a second connection to the same server with a user that has it, and name that one:
SAILFISH_DB_CONNECTION=mysql_sailfish
SAILFISH_SCHEMAS=app,billing
performance_schema is server-wide, so a connection on the same server can watch any schema on it. The
sailfish_* tables are written to the database that connection points at.
Statement digests#
Each collection reads only the digests that ran since the previous one, most recently run first, up to
SAILFISH_DIGEST_LIMIT. The cap matters only after a long gap. A digest it skips is not lost: its
counters are cumulative, so the next collection that reads it records everything it missed. If your digests are
empty, see statement digests.
Transactions#
Each collection reads the transactions that finished since the previous one: committed against rolled back, and
those that ran at least long_seconds, with the account and program that ran them. Never their
statements' text.
'transactions' => [
'long_seconds' => (float) env('SAILFISH_LONG_TRANSACTION_SECONDS', 5),
],
A shorter threshold keeps more rows in sailfish_long_transactions. The
long transaction event can be set higher than
this with its own min_seconds, never lower, since shorter transactions are not kept. Where the history
comes from, and why it may be a sample, is in
what gets recorded.
Settings#
Each collection reads every global variable and keeps its value, to see it change. A value that may be a secret is
never kept, only a fingerprint of it keyed with APP_KEY, so a change still shows as
hidden (a1b2c3d4). That covers a variable whose name ends in password, pwd,
token and the like or has secret in it, and init_connect,
init_replica and init_slave, which hold SQL. Name any other variable that can hold a secret:
'settings' => [
'hidden' => ['my_plugin_api_key'],
],
The next collection masks what is already kept of it, its changes and events alike. What was already sent by mail,
Slack or webhook stays sent, so change a secret that got that far. Rotating APP_KEY, or taking a name
back out of hidden, shows each such value as changed once.
To stop a setting from opening events, or from showing on the dashboard, name it in the setting change detector's
ignore instead (see events).
Redis#
'redis' => [
'connection' => env('SAILFISH_REDIS_CONNECTION'),
'timeout' => (float) env('SAILFISH_REDIS_TIMEOUT', 2),
],
connection is a name from database.redis, such as default or
cache. Sailfish reads it over a connection of its own, configured like that one but giving up after
timeout seconds, so a Redis that does not answer is recorded as unread rather than holding up the
collection. A cluster connection is refused. See Redis.
Cache#
'cache' => [
'enabled' => env('SAILFISH_CACHE_ENABLED', false),
'connection' => env('SAILFISH_CACHE_REDIS_CONNECTION'), // null: redis.connection
'depth' => (int) env('SAILFISH_CACHE_KEY_DEPTH', 1),
'separator' => ':',
'groups' => [],
'ignore' => ['illuminate:*', 'framework/schedule-*'],
'max_entries' => 100_000,
'idle_hours' => 24,
'max_groups' => 1_000,
],
Nothing is recorded without a Redis connection to buffer the counts in. groups names groups of your own
by pattern, ignore leaves keys out, and max_entries caps how many entries are followed from
write to expiry at once, about 100 bytes of Redis each. One cached forever is let go once nothing has read or
written it for idle_hours. Past max_groups, new groups are counted together as
(other). See Cache for how keys are grouped.
Dashboard#
'domain' => env('SAILFISH_DOMAIN'),
'path' => env('SAILFISH_PATH', 'sailfish'),
'middleware' => ['web'],
'dashboard' => [
'windows' => [1, 7, 30, 90], // days the charts offer
'default_window' => 7,
'per_page' => 100,
],
The dashboard runs through middleware and then Sailfish's own check against the
viewSailfish gate. default_window should be one of windows.
Detectors#
Every detector has a key under detectors with an enabled flag and its thresholds. To turn
one off, or to make the table-scan surge less sensitive:
'detectors' => [
'scan_surge' => [
'enabled' => true,
'history_days' => 7,
'ratio' => 3,
'min_rows_per_hour' => 100_000,
'min_rows' => 1_000,
],
'no_primary_key' => [
'enabled' => false,
],
// ...
],
Events lists every detector with its key and the thresholds it takes.
Notifications#
notifications.types gives each event type a severity (critical, warning or
info) and says whether it is sent immediately, in the digest, or
none at all. notifications.routes picks channels per severity. Both are covered in
notifications.
Retention#
'retention' => [
'raw_days' => 7,
'hourly_days' => 90,
'digest_days' => 90,
'cache_key_days' => 90,
'long_transaction_days' => 30,
],
null keeps that granularity, those digests, those cache key groups or those transactions forever. See
retention and rollups.