Configuration - Joomla

Where the configuration lives

Everything is under System → Plugins → System - DockRay → Options. The screen shows a live configuration status, the result of the last test and a Send a test event button that checks the connection without leaving the page.

Without a token and a private key the plugin stays inert.

Configuration source

Values can come from this screen or from PHP constants defined in configuration.php:

define('DOCKRAY_TOKEN', 'project-token');
define('DOCKRAY_PRIVATE_KEY', 'project-private-key');

The remaining constants override their fields the same way: DOCKRAY_URL, DOCKRAY_ENVIRONMENT, DOCKRAY_RELEASE, DOCKRAY_TRACES_SAMPLE_RATE, DOCKRAY_SEND_DEFAULT_USER, DOCKRAY_SEND_DEFAULT_PII, DOCKRAY_JS_ERRORS and DOCKRAY_JS_SAMPLE_RATE. The status area lists exactly which ones are currently in effect.

Environments

Every environment should report under an unambiguous name - production, staging, preview. The name is a column in the panel and a filter on the error list, so without it a production outage looks exactly like an error someone triggered in a test. Leave your local environment without credentials: with no token and no key the integration loads and stays silent, so you do not need a separate switch to turn it off.

The events the plugin listens to

onError is never stopped - handling the error stays Joomla's job, DockRay only reports it. Nothing goes out during the request: events queue up and leave from a shutdown handler once the response has been flushed.

User data and privacy

Two independent switches. Attach the logged-in user sends the id, username and e-mail address - handy for back-end errors, but it brings personal data into monitoring. Send IP address and user agent is a separate decision and is off by default.

JavaScript errors

Off by default. Once enabled, the site loads a collector that reports window.onerror and unhandled promise rejections to Joomla, not to the panel: a browser cannot authenticate against DockRay without the project private key, which would then be readable in page source. Joomla forwards each error with its own key.

Reports go to com_ajax (index.php?option=com_ajax&group=system&plugin=dockray), limited to 16 KB per report. The collector is inlined into the page rather than linked, because the plugin directory is not an asset directory in Joomla.

Reporting by hand

use function Dock\Ray\captureException;

try {
    $model->save($data);
} catch (\Throwable $exception) {
    captureException($exception);

    throw $exception;
}

The plugin installs its hub as the SDK's current one, so the global functions work anywhere in the request once the plugin has initialised.

Protecting the private key

The private key is a project secret, not an identifier. Keep it in environment variables, in a secrets manager or in the server configuration - never in the repository, in logs, in a screenshot or in code sent to the browser. One project can hold many keys, so production and staging should each get their own: either can be revoked on its own without interrupting the others. A suspicion that a key leaked is reason enough to revoke it and generate a new one.