Configuration

Updated

Telltale needs no configuration to run. Scalpels installs it with no environment values, because it has no secret of its own and every setting has a working default. Ingest values are minted on the dashboard, not set in the environment.

This page lists the settings you can override if the defaults do not suit you.

Server settings

These are read from the Telltale deployment's environment in Laravel Cloud. Set one only to change its default.

Variable	Default	What it controls
`TELLTALE_MAX_BODY_BYTES`	`1048576` (1 MiB)	Largest request body accepted at `/api/register` and `/api/ingest`, measured both compressed and after gzip decoding. Larger requests get `413`.
`TELLTALE_MAX_EVENTS_PER_BATCH`	`100`	Most events allowed in one ingest batch. Larger batches get `422`.
`TELLTALE_IP_RATE_PER_MINUTE`	`240`	Requests per minute from one IP address to the device endpoints.
`TELLTALE_APP_RATE_PER_MINUTE`	`120`	Default requests per minute for one app, applied to new apps.
`TELLTALE_INSTALL_RATE_PER_MINUTE`	`60`	Default requests per minute for one install, applied to new apps.
`TELLTALE_APP_DAILY_EVENT_CAP`	`100000`	Default events per UTC day for one app, applied to new apps.
`TELLTALE_INSTALL_DAILY_EVENT_CAP`	`10000`	Default events per UTC day for one install, applied to new apps.
`TELLTALE_SESSION_INACTIVITY_MINUTES`	`30`	Gap after which the server treats events as a new session.
`TELLTALE_RAW_EVENT_RETENTION_DAYS`	`90`	How long raw events are kept before the daily prune deletes them.

Per-app limits are fixed when the app is created

The four per-app and per-install limits are copied onto each app when you create it. Changing those variables later only affects apps created afterwards; existing apps keep the limits they were created with. The dashboard and MCP tools do not offer a way to edit an existing app's limits.

Retention

Retention is enforced by the scheduled telltale:prune-events command, which Scalpels' scheduler runs daily at 03:10. You can also run it by hand, with an optional override:

php artisan telltale:prune-events --days=30

Pruning deletes raw events only. Sessions, daily aggregates and error group totals are preserved. Shortening retention shortens how far back funnel, screen flow, error list and timeline queries can see.

Client settings

The client in your NativePHP app reads two values from the build environment: TELLTALE_URL and TELLTALE_INGEST (see Instrumenting your app). Everything else has a default in the package's config/telltale.php. Publish it to change one:

php artisan vendor:publish --tag=telltale-config

Key	Default	What it controls
`database`	`database_path('telltale.sqlite')`	Location of the local SQLite outbox.
`batch_size`	`100`	Events sent per ingest request. Keep it at or below the server's batch limit.
`max_rows`	`10000`	Most events held in the outbox; older ones are dropped and counted.
`max_age_seconds`	30 days	Events older than this are dropped from the outbox and counted.
`http_timeout_seconds`	`10`	Timeout for registration and ingest requests.
`capture.enabled`	`true`	Set `false` to turn off automatic capture of screens, sessions and errors.
`capture.platform`	`auto`	Detects mobile or desktop; set `mobile` or `desktop` to force one.
`session.inactivity_seconds`	30 minutes	Inactivity gap that starts a new session on the device.
`trace_header.enabled`	`true`	Adds `X-Telltale-Session` to your app's outbound HTTP requests.
`backoff.initial_seconds`, `backoff.maximum_seconds`	`15`, `3600`	Retry backoff after a failed delivery.
`queue.connection`	`database`	Queue used to drain the outbox. A `sync` or empty connection disables queued draining.
`queue.name`	`null`	Queue name for drain jobs.
`queue.auto_dispatch`	`true`	Dispatches a drain job automatically after events are captured.
`queue.deduplicate_seconds`	`15`	Minimum gap between automatically dispatched drain jobs.