Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/wikioasis/mw-config/llms.txt

Use this file to discover all available pages before exploring further.

WikiOasis runs two complementary observability systems: Sentry captures errors, exceptions, and distributed traces from every PHP request, while DogStatsD ships application metrics to a StatsD-compatible endpoint. Together they provide real-time visibility into application health, slow requests, and database errors without requiring any manual instrumentation at the wiki level. A public Instatus status page at status.wikioasis.org surfaces ongoing incidents to end users.

​
Monitoring Components

ToolPurposeConfig Location
Sentry PHP SDKError capture, distributed tracing, profilingSentry.php
Sentry Browser SDKClient-side error capture (JS)Sentry.php (injected via hook)
Monolog → SentryLog-level routing: exceptions, DB errorsSentry.php
DogStatsDApplication metrics (counters, timers)LocalSettings.php
Instatus widgetPublic status page and maintenance pageDatabaseMaintenance.php

​
Sentry Configuration

Sentry.php initialises the Sentry PHP SDK immediately after PrivateSettings.php is loaded, so every subsequent line of the MediaWiki bootstrap is covered by the active Sentry hub. 
\Sentry\init( [
    'dsn'                  => $sentryDSN,
    'environment'          => defined( 'MW_ENV' ) ? MW_ENV : 'production',
    'release'              => $wgVersion ?? null,
    'enable_logs'          => true,
    'traces_sample_rate'   => 1.0,
    'profiles_sample_rate' => 0.3,
    'attach_stacktrace'    => true,
    'max_breadcrumbs'      => 100,
] );

100% Trace Sampling

traces_sample_rate = 1.0 — every HTTP request generates a Sentry transaction. This gives complete request-level visibility but may require Sentry plan capacity planning as traffic grows.

30% Profiling

profiles_sample_rate = 0.3 — 30% of traced requests also capture a continuous CPU profile, providing function-level performance data without the overhead of profiling every request.

Stacktrace Attachment

attach_stacktrace = true — every captured message (not just exceptions) includes a full PHP stack trace, making it easier to pinpoint the source of informational warnings and non-fatal log entries.

Breadcrumb Depth

max_breadcrumbs = 100 — up to 100 structured breadcrumb events (log entries, DB queries, HTTP calls) are retained per transaction, providing rich context for post-mortem debugging.

​
Environment and Release

  • Environment is read from the MW_ENV PHP constant. If the constant is not defined, it defaults to 'production'. The beta realm (hostname staging11) should define MW_ENV=staging to keep staging events in a separate Sentry environment.
  • Release is set to $wgVersion, so every MediaWiki version upgrade automatically creates a new Sentry release, enabling regression tracking across deployments.
When running MediaWiki on the staging server, set define('MW_ENV', 'staging') before including Sentry.php. This routes all errors and traces to the staging environment in Sentry, preventing test noise from contaminating production dashboards and alerts.

​
Monolog Integration

All standard MediaWiki log channels are routed through a Monolog SPI that sends records to Sentry via two dedicated handlers plus a stderr stream:
HandlerClassMinimum Level
sentry-logsSentry\Monolog\LogsHandlerINFO
sentry-crumbsSentry\Monolog\BreadcrumbHandlerDEBUG
stderrMonolog\Handler\StreamHandlerDEBUG
The following loggers are explicitly configured to use all three handlers:
Captures every PHP exception that passes through MediaWiki’s logging infrastructure. Works in tandem with the LogException hook for exceptions raised during page rendering.
Captures PHP-level errors (warnings, notices) that MediaWiki converts into log entries. The attach_stacktrace setting ensures these arrive in Sentry with full call-stack context.
Routes all MediaWiki database-layer errors (connection failures, query errors, deadlocks) to Sentry. These are also written to php://stderr via the stderr handler, making them visible in server logs.
Any log channel not explicitly named in the Monolog config falls through to @default, which routes to the same three handlers. This ensures no log record is silently dropped.

​
HTTP Transaction Tracking

For non-CLI requests, Sentry.php creates a TransactionContext that records the HTTP method and URI path (query string stripped) as the transaction name: 
$sentryTxCtx = new \Sentry\Tracing\TransactionContext();
$sentryTxCtx->setName(
    ( $_SERVER['REQUEST_METHOD'] ?? 'GET' ) . ' ' .
    strtok( $_SERVER['REQUEST_URI'] ?? '/', '?' )
);
$sentryTxCtx->setOp( 'http.server' );
$sentryTx = \Sentry\startTransaction( $sentryTxCtx );
A PHP shutdown function finishes the transaction, sets the HTTP response code, and flushes the Sentry SDK — ensuring traces are captured even when execution terminates via die() or a fatal error.

​
MediaWiki Hook Integrations

LogException Hook

Captures any Throwable that MediaWiki logs and is not suppressed ($suppressed === false). Suppressed exceptions (e.g. expected 404s) are intentionally excluded to reduce noise.

UserGetRights Hook

Sets Sentry user context (id and username) for every authenticated request. This allows Sentry issues to be filtered and searched by affected user account.

BeforePageDisplay Hook

Injects the Sentry Browser SDK <script> tag into every page’s <head>, enabling client-side JavaScript error capture and session replays in addition to the server-side PHP integration.

​
Fatal Error Capture

Both web and CLI shutdown functions call error_get_last() and send any fatal-class error (E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR) to Sentry as a fatal-severity message before flushing the SDK: 
register_shutdown_function( static function () use ( $sentryTx ) {
    $error = error_get_last();
    if ( $error && in_array( $error['type'], [ E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR ], true ) ) {
        \Sentry\captureMessage( $error['message'], \Sentry\Severity::fatal() );
    }
    $sentryTx->finish();
    \Sentry\flush();
} );

​
DogStatsD Metrics

Application-level counters, timers, and gauges are emitted in DogStatsD format via UDP: 
$wgStatsFormat  = 'dogstatsd';
$wgStatsTarget  = 'udp://monitoring-us-east-021.ovvin.wonet:9125';
$wgWMEStatsdBaseUri = 'udp://monitoring-us-east-021.ovvin.wonet:9125';
Both $wgStatsTarget (MediaWiki core stats) and $wgWMEStatsdBaseUri (WikimediaEvents extension) point to the same endpoint on monitoring-us-east-021.ovvin.wonet. The DogStatsD format adds tag support on top of plain StatsD, enabling per-wiki and per-cluster metric filtering in any compatible metrics backend (e.g. Datadog, VictoriaMetrics, Grafana).

​
Status Page and Maintenance Mode

The public status page at https://status.wikioasis.org/ is powered by Instatus and is the canonical source of truth for ongoing incidents and scheduled maintenance windows. During database maintenance, DatabaseMaintenance.php serves an HTTP 503 response with links to the status page and the WikiOasis Discord server. An Instatus status widget is embedded directly in the maintenance page so users can check current incident status without navigating away.
The readOnlyBySection entries in Database.php and the 503 maintenance page in DatabaseMaintenance.php are complementary mechanisms. Read-only mode allows reads to continue while blocking writes; the 503 page is used when the cluster must be taken fully offline (e.g. for schema migrations).

Build docs developers (and LLMs) love

Get started for freeTalk to us