Configuration - Drupal

Where the configuration lives

Administration → Configuration → Development → DockRay, that is /admin/config/development/dock-ray. The form 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.

Configuration source

Configuration source decides how a settings.php override and the form's own saved values interact:

Locked fields are shown with the value actually in effect and a note explaining why. They still submit that value with the rest of the form: a disabled Form API element commits #default_value instead of dropping the key, so saving while a field is locked cannot blank what is stored.

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.

How reporting works

The module registers a logger channel. Drupal already turns every PHP error and every uncaught exception into a log entry, so one channel covers the lot - and there is no second error handler competing with the core one.

minimum_level is an RFC 5424 severity: 3 (Error) reports errors, criticals, alerts and emergencies, and ignores warnings and notices. An entry carrying an exception is reported with its stack trace; the rest become messages.

Transactions

Request handling is measured only when traces_sample_rate is above zero. A transaction opens on kernel.request and closes on kernel.terminate. Nothing goes out during the request: events queue up and leave from a shutdown handler once the response has been flushed, so a slow panel never delays a page.

JavaScript errors

Off by default. Once enabled, the module loads a collector on non-admin pages that reports window.onerror and unhandled promise rejections to the site, not to the panel: a browser cannot authenticate against DockRay without the private key, which would then be readable in page source.

Reports go to POST /dock-ray/browser-error, limited to 16 KB and rate limited through Drupal's flood service to 20 per IP address per hour. The collector itself is served from /dock-ray/collector.js, because the SDK lives in the project's vendor/ directory, outside the docroot on most installs. Every request answers 202 whether or not the report was accepted.

Reporting by hand

try {
  $this->import();
}
catch (\Throwable $exception) {
  \Drupal::service('dock_ray.hub')->captureException($exception);

  throw $exception;
}

\Drupal::logger('my_module')->error(...) reaches DockRay as well - through the same channel as everything else, so your own code needs no separate integration.

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.