Skip to content

Logging & bug reports

All logging goes through Serilog (4.4.0). The console sink is configured to reproduce the original's byte-exact output — the parity suite (which compares raw stdout/stderr) is the contract, and it stays green.

Levels and sinks

Sink Min level Output
Console (stdout) Information engine verbose messages (-v) and program logs
Console (stderr) Error engine error messages (via standardErrorFromLevel)
Bug report API Warning Warning+ events, except expected engine error callbacks

Logging levels used by the code:

Level Used for
Information engine verbose callback (registered only with -v — parity-gated)
Error engine error callback (stderr — parity-gated)
Fatal unhandled exceptions in Program.Main
Debug expected-handling catch blocks (FileUtil, Hash3DS, usage telemetry) — below the console threshold, so parity output is never affected

Bug report forwarding

Warning+ events are POSTed to the bug report API (AspNet_BugReportEmailService — see its InstructionsToSendBugs.md):

POST {url}/api/send-bug-report
X-API-KEY: {api key}
Content-Type: application/json

Engine error callbacks (for example Could not open file when the user passes a missing path) are expected input errors, not application bugs. They are still written to stderr for parity but carry the BugReportSuppressed property, which keeps them out of the bug report API.

Configuration (environment variables)

Variable Default Purpose
RASHARP_BUGREPORT_API_KEY (decoded Constants.BugReportApiKey) optional override of the built-in API key
RASHARP_BUGREPORT_URL https://www.purelogiccode.com/bugreport/api/send-bug-report endpoint override
RASHARP_BUGREPORT_DISABLE (unset) set to 1 to force forwarding off

The built-in API key lives in RetroAchievementsSharp.Cli/Constants.cs double-encoded (Base64 applied twice) so it is not readable in the source tree; the application decodes it at startup and uses the real value. An explicit RASHARP_BUGREPORT_API_KEY always takes precedence.

Test runs never report

The parity harness sets RASHARP_BUGREPORT_DISABLE=1 on every child process, so dotnet test never POSTs to the real API.

Every report contains

=== Environment Details ===
Date: 2026-08-12 01:08:03 -03:00
Application Name: RetroAchievementsSharp
Application Version: 1.8.3
OS Version: Microsoft Windows NT 10.0.26200.0
Architecture: X64
Bitness: 64
Windows Version: 10.0.26200.0
Processor Count: 24
Base Directory: ...
Temp Path: ...

=== Error Details ===
<the log message>

=== Exception Details ===        (only when an exception is logged)
Type: ...
Message: ...
Source: ...
StackTrace: ...

The payload also maps applicationName, version, environment and stackTrace (≤ 8000 chars) to the API's structured fields; the message block is capped at 4000 chars.

Reliability rules

  • The sink never writes to stdout/stderr — parity output is untouched.
  • All transport/API failures are swallowed: reporting is best-effort and logging must never break the application.
  • A 5-second cooldown keeps the CLI under the API's 10 req/min rate limit.
  • On shutdown (Log.CloseAndFlush), pending reports get up to 2 seconds to complete.

Usage telemetry

At application launch the CLI reports a usage hit to the ApplicationStats API (AspNet_ApplicationStats — see its InstructionsToUseApiEndpoints.md):

POST {url}
Authorization: Bearer {api key}
{"applicationId": "RetroAchievementsSharp", "version": "1.8.3"}

Configuration (environment variables)

Variable Default Purpose
RASHARP_STATS_API_KEY decoded Constants.BugReportApiKey optional override
RASHARP_STATS_URL https://www.purelogiccode.com/ApplicationStats/stats endpoint override
RASHARP_STATS_DISABLE (unset) set to 1 to disable usage reporting

Same rules as the bug-report sink: never writes to stdout/stderr, all failures swallowed (the server rate-limits at 1 call/hour/IP/app and answers 429 — ignored), fire-and-forget with up to 2 seconds to finish at process exit. The parity harness sets RASHARP_STATS_DISABLE=1, so test runs never report.

try/catch + Log policy

Public entry points log and degrade gracefully instead of crashing:

  • Program.Main — wraps the whole run: Log.Fatal(ex, ...), prints a summary to stderr, exits 1 (the original segfaulted on some malformed invocations; this is the documented hardening).
  • RcHash.GenerateFromFile / GenerateFromBuffer — catch, Log.Error, return false (the API's failure contract).
  • Expected-handling catch blocks (FileUtil.FullPath/OpenFile/LoadZippedFile, Hash3DS key loading) — Log.Debug with the exception; the parity error message is still emitted by the engine callback as before.