Sailfish

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#

VariableDefaultWhat it does
SAILFISH_ENABLEDtrueMaster switch. When false Sailfish registers no commands, no schedule and no dashboard. Its migrations still load.
SAILFISH_DB_CONNECTIONapp defaultRead performance_schema from here, and store the sailfish_* tables here
SAILFISH_SCHEMASthe connection's databaseComma-separated databases whose tables, indexes and statements are recorded
SAILFISH_DIGEST_LIMIT1000Most statement digests read per collection
SAILFISH_SCHEDULE_ENABLEDtruePut the commands on the scheduler. False to schedule them yourself.
SAILFISH_PATHsailfishWhere the dashboard is served
SAILFISH_DOMAINnoneServe the dashboard on this domain only
SAILFISH_NOTIFY_CHANNELSnoneComma-separated: mail, slack, webhook
SAILFISH_NOTIFY_MAILnoneComma-separated addresses
SAILFISH_SLACK_WEBHOOK_URLnoneAn incoming webhook, or a #channel to post to through the bot token
SAILFISH_WEBHOOK_URLnoneWhere the webhook channel POSTs JSON
SAILFISH_NOTIFY_REPEAT_MINUTES360Send an immediate event again while it stays open this long. 0 never repeats.
SAILFISH_DAILY_DIGEST_AT09:00When the daily digest goes out
SAILFISH_ROLLUP_AT03:00When sailfish:rollup runs
SAILFISH_LONG_TRANSACTION_SECONDS5Keep each finished transaction that ran at least this long (see transactions)
SAILFISH_REDIS_CONNECTIONnoneOne of the application's Redis connections to read INFO from as well (see Redis)
SAILFISH_REDIS_TIMEOUT2Seconds to wait for Redis to connect or answer before recording it as unread
SAILFISH_CACHE_ENABLEDfalseCount what the application does with its cache, for each group of keys (see cache)
SAILFISH_CACHE_REDIS_CONNECTIONSAILFISH_REDIS_CONNECTIONThe Redis connection the application's processes leave those counts in until a collection takes them
SAILFISH_CACHE_KEY_DEPTH1How 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.

Install Sailfish today.

Checkout ends with your license key, and the installation guide takes it from there.