3. Getting reports safely into your hands

A useful report has to survive more than the exception. It must be written under the application's real account, survive a failed network request, arrive with its attachments, and remain readable by the investigator. A successful connection test proves only part of that journey.

Use this chapter after the first-report exercise in chapter 1. Keep the matching build artifacts described in chapter 2. The end-to-end check in section 3.9 finishes by opening the received file, not by trusting a success dialog.

3.1 Decide what happens when nobody can click a button

Open Project / EurekaLog options for the application, select the correct application type, and make three separate decisions: what to save, what to show, and where to send. Selecting a dialog is not the same as selecting a sender.

For a noninteractive application, turn off Sending / Options / Show send progress, Show success message, and Show failure message. Set Screenshot capture to Do not take screenshot. The documented recommendation is also to turn off Send in separate thread when no UI dialog is used. That option is not a persistent background delivery queue: the exception thread waits for the sending thread, while processing UI messages. Some exceptional contexts override its use.

To send without asking in a visual dialog, the documented combination is to disable Ask user for send consent and enable Default choice: send report. Do this only within an appropriate privacy and consent policy. For no visual dialog, use (none) and configure sending normally. Do not confuse that with an exception filter whose handler is none or RTL: those choices do not send a EurekaLog report. A filter can retain the EurekaLog handler and select dialog type (none).

Thread monitoring and handling are separate prerequisites. A sender cannot deliver an exception that never reaches EurekaLog's processing path; see chapters 8, 15, and 16.

3.2 Keep a usable local copy

In Bug report, enable Save bug report to file and choose its folder. The local file is the text .el report; .elx is the XML sending format, and .elp is a ZIP package containing the report and associated files. A local .el is not automatically a backup of everything in an outgoing .elp.

An empty report folder selects the documented default beneath:

%APPDATA%\Neos Eureka S.r.l\Bug reports\

The application/project determines the subfolder and filename. Start / Programs / EurekaLog / Bug reports opens the reports area on a developer machine. '.\' selects the executable's directory; '.\Reports' selects a subdirectory there. Neither is a good deployment choice if the executable is installed in a protected directory.

Configure a location that the actual runtime account can create and write. %APPDATA% belongs to that account; a service's reports are not necessarily in the logged-in developer's profile. Establish who can read the reports, how operators find them, how much storage is allowed, and when they expire. Treat report files as potentially sensitive application data, not harmless diagnostic text.

The documented behavior is to create a missing directory and fall back to the default folder if the chosen directory is write-protected. Consequently, “nothing is in the folder I configured” does not by itself mean report generation failed. Check the effective account and its default reports folder as well. Do not rely on fallback as a permissions strategy: verify the intended location during deployment.

Three options determine how much history remains:

• Max reports in one file is a count, not a byte limit. A value of 1 replaces the previous report; larger values append reports and eventually remove the oldest.
• Do not save duplicate errors groups by BugID and increases the stored occurrence count instead of appending another matching report. This reduces volume but can discard useful variation between occurrences.
• Delete file at version change requires meaningful executable version information. Enable it only if discarding the previous version's local evidence is intentional.

During delivery commissioning, leave Sending / Options / Delete bug report after sending off. When enabled, it deletes the local report after a successful sending result, but not after a declined or failed send. That success result can represent tracker workflow handling or a fallback sender; it is not proof that your preferred inbox contains every attachment.

3.3 Collect less, deliver enough

Use Bug report / Content to select information that answers questions about your application. For a service, account and privileges may be useful; printer information is useful for a printing problem, not for every program. Unnecessary collection adds work while handling an exception and increases the amount of private data you must protect.

In Sending / Options:

1. Start with the current report and no screenshot. Enable Send report in XML format only if your receiving workflow needs .elx instead of .el.
2. Enable Pack send files into single file when sending multiple files. It produces an .elp; some send methods cannot handle several separate attachments.
3. Add only known, bounded files through Additional files. Separate paths with ;. Relative paths are resolved against the application's folder, not its current working directory. Environment variables can locate per-user data.
4. For files generated at report time, use OnZippedFilesRequest to add files inside the package and OnAttachedFilesRequest to attach files beside it. Chapter 24 covers event integration. Use the event's ATempFolder for generated temporary attachments; do not assume those files remain after sending ends.
5. Decide whether Send entire bug report file with multiple reports is appropriate. It can resend older reports and make each upload larger. It has no useful effect when local storage holds only one report or is disabled.

Review configuration files, application logs, document contents, user names, machine names, and reproduction text before collecting them. Passwords, session tokens, and connection strings often hide in otherwise useful attachments. Screen capture can include other applications: even Capture my application's windows only describes a bounding rectangle, not a guarantee that every visible pixel belongs to your application. Prefer Capture my application's active window only when a screenshot is justified, and verify its output.

Pack with password protects the .elp in transit/storage according to the implemented archive mechanism; it is not a secret vault on the client's computer. The password is recoverable from an executable that must use it. It is different from Debug information encryption password, which protects symbol names rather than every report field or attachment. Use authenticated encrypted transport and access-controlled storage; do not claim modern cryptographic guarantees merely because an option says “password” or “SSL”.

3.4 Select a primary delivery route

In Sending, check the method to enable it and configure its panel. Selecting several methods creates an ordered fallback list, not a broadcast list: EurekaLog tries the next method only after the previous one fails, and stops when one succeeds.

A practical starting point is one controlled SMTP Client or HTTPS route plus a recoverable local copy. Add fallback only when it works in the deployment environment. In particular, omit Shell if you depend on failure-triggered backup or offline storage: putting it last does not fix its false-success boundary.

Credentials belong to a limited reporting identity

Create a separate reporting account, preferably separate for each product. Never embed a personal or administrator account. Encrypted settings inside an EXE are still recoverable: the process must decrypt or otherwise use the credential. An API token can be revoked and may have narrower permissions, but it is still a credential.

For a tracker, scope the account to the automatic-reporting project and only the operations the chosen sender actually needs: create, search/read, update the occurrence field or comment, and upload files. A create-only account may pass the first submission and fail on the second. Keep your manually managed engineering project outside its reach. Disable account/profile changes where the tracker supports it.

If the built-in API requires privileges you cannot safely distribute, put an HTTP facade in front of the tracker. The facade receives a bounded report and performs tracker operations with server-held credentials. Anonymous intake avoids shipping a reusable secret, but still needs abuse controls, size limits, storage isolation, and authorization for investigators. It does not become safe merely by omitting a password.

SMTP Client: configure a real mailbox

Obtain these values from the administrator or provider of a reporting-only mailbox. Provider policy is external; historical examples of consumer-mail settings are not a promise that password authentication is still allowed.

1. Select SMTP Client in Sending.
2. Enter Address(es) for the report recipients; multiple addresses can be separated by , or ;.
3. Set From field to an address that this SMTP account may send as. Use a fixed display name, such as "Application Reports" <reporter@example.com>, rather than allowing the current Windows user name to become the display name. Replace the example address with the provisioned reporting address.
4. Enter Host / server, Port, UserID / login, and Password. The documented authentication methods are AUTH LOGIN and AUTH PLAIN; this is not a documented OAuth flow. If policy requires an application password and the provider offers one, use it. If the provider accepts neither supported authentication method, use another transport or your own facade.
5. Select the encryption mode required by that endpoint. In these options SSL means immediate/implicit encryption, commonly port 465; TLS means a plain connection followed by STARTTLS, commonly port 587 (sometimes 25). Do not select a port and mode independently.
6. Keep Use user-supplied e-mail off unless the server explicitly permits sending with that address. Otherwise a customer email in the From field can cause rejection. User contact data can remain in the report instead.
7. Set a recognizable E-mail subject and optional E-mail message. Append bug report text in the message text adds text; it does not replace the attached report. Account for both in the mail-size limit.
8. Test arrival in the actual mailbox, including filtering/quarantine, then download and open the attachment.

A security-critical legacy behavior: fallback to plain mode when the explicit upgrade command fails is documented for the SSL/TLS sender. Therefore checking TLS is not evidence that encryption is mandatory. Use a server policy that rejects unencrypted authentication/submission, verify the negotiated behavior of your EurekaLog build, or use a suitable implicit-encryption/HTTPS route. The labels do not establish a minimum TLS protocol version or certificate-validation policy.

3.5 HTTP upload: agree on the request and the receipt

HTTP upload submits a web form with file uploads. Provision an HTTPS endpoint with a certificate and an upload handler, plus a private writable destination outside the public web root. An administrator must configure hosting, authentication, request limits, and permissions; EurekaLog does not create the receiving service for you.

Configure Sending / HTTP upload as follows:

Do not paste a browser request indiscriminately. In particular, overriding Content-Type with application/x-www-form-urlencoded sends fields without files. Use the normal file-upload request when attachments are required. A form or collector that needs URL-encoded fields requires a separate, implemented attachment-upload step; successful issue creation is not that step.

A small receiver with an explicit success boundary

The following PHP 8 example is a single packed-report receiver, not a tracker. It accepts exactly one .elp from a project with Pack send files into single file enabled and no extra outside-package attachments. It assigns a random server filename, stores the report privately, and reports success only after the upload is moved to that destination. It does not execute or extract the archive.

Before installing it, create a private directory and give only the web-service identity write access and investigators appropriate read access. Set the server-side EL_REPORT_DIR environment variable to that directory. Configure HTTPS and the chosen intake access policy in the web server. Set request, PHP upload, and proxy limits consistently; the example's limit is 8 MiB, an example application policy, not an EurekaLog limit. A web server rejecting a request before PHP runs must return a failure rather than a successful login/error page.

Save this as the endpoint's upload.php:

<?php
// PHP 8. Keep error details in server logs, not in responses.
ini_set('display_errors', '0');
header('Content-Type: text/html; charset=UTF-8');

try {
    if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST') {
        throw new RuntimeException('POST required');
    }
    if (count($_FILES) !== 1) {
        throw new RuntimeException('Exactly one packed report required');
    }
    $file = reset($_FILES);
    if (!is_array($file)
        || !isset($file['error'], $file['tmp_name'], $file['name'], $file['size'])
        || is_array($file['error'])
        || $file['error'] !== UPLOAD_ERR_OK
        || !is_string($file['name'])
        || strtolower(pathinfo($file['name'], PATHINFO_EXTENSION)) !== 'elp'
        || $file['size'] < 1 || $file['size'] > 8 * 1024 * 1024
        || !is_uploaded_file($file['tmp_name'])) {
        throw new RuntimeException('Invalid or oversized upload');
    }
    $root = getenv('EL_REPORT_DIR');
    if (!$root || !is_dir($root) || !is_writable($root)) {
        throw new RuntimeException('Report directory unavailable');
    }
    // A unique directory prevents client names from overwriting other reports.
    $receipt = bin2hex(random_bytes(16));
    $directory = rtrim($root, '/\\') . DIRECTORY_SEPARATOR . $receipt;
    if (!mkdir($directory, 0700)) {
        throw new RuntimeException('Cannot create report directory');
    }
    if (!move_uploaded_file($file['tmp_name'],
                            $directory . DIRECTORY_SEPARATOR . 'report.elp')) {
        rmdir($directory);
        throw new RuntimeException('Cannot store report');
    }
    echo '<html><body><EurekaLogStatus>0</EurekaLogStatus>';
    echo '<EurekaLogReply>Report stored: ' . $receipt . '</EurekaLogReply>';
    echo '</body></html>';
} catch (Throwable $error) {
    error_log('Report intake: ' . $error->getMessage());
    http_response_code(500);
    echo '<html><body><EurekaLogStatus>$8000FFFF</EurekaLogStatus>';
    echo '<EurekaLogReply>Report was not accepted.</EurekaLogReply>';
    echo '</body></html>';
}

The extension check is a routing rule, not proof that the file is safe. Keep the directory private, apply a retention/quota policy, monitor failures and available space, and treat every upload as untrusted. If you expose anonymous intake, configure rate and storage controls at the server; this script alone is not an abuse-resistant public service. If you need several attachments, change the receiver contract deliberately rather than silently accepting only the first.

EurekaLog recognizes EurekaLogStatus and EurekaLogReply in the returned HTML, including within comments. The status is a numeric TSendResult, not a name such as srSent: 0 represents srSent; $8000FFFF represents srUnknownError (E_UNEXPECTED). Without a status tag, the documented default is srSent. This is why a receiver must not return a cheerful HTTP page after storage failed. A reply containing a URL can open a browser, so keep unattended-operation replies to plain text.

Once the receiver stores a report, investigators can retrieve the private file through your controlled server-access workflow and open it as described in chapter 4. If the receiver also posts to a tracker, define whether its acknowledgement means “durably accepted for later processing” or “tracker issue and attachment both committed”. Do not present a queue receipt as confirmation of tracker delivery.

3.6 Connect a built-in tracker without giving away the tracker

Built-in tracker setup follows the same sequence regardless of product:

1. Create a separate automatic-reporting project/repository, an appropriate category or issue type, and a limited reporting identity.
2. Enable the API used by the integration. Create the required token or compatible login credentials.
3. Create the desired occurrence and BugID fields, attach them to the project, expose them on creation/update screens where required, and permit the reporter to read/write them. Record the field names expected by the sender.
4. In the selected sender panel, enter the host/path without a scheme or embedded port, select HTTPS and the correct port, and enter the sender's credentials. HTTP BasicAuth, when offered, is a separate web-server authentication layer. Configure proxy settings if the runtime account cannot use system settings.
5. Click Connect to populate the available values. Select the actual project and mandatory issue type/category/component. Do not assume a visible project key is interchangeable with the project name.
6. Map workflow statuses, count/BugID/contact fields, and version handling. Decide whether later occurrences should upload more report files. Use distinct outgoing names if multiple files will accumulate.
7. Run new, repeated, and closed-issue submissions, then repeat from the actual application. Check the stored file, not only the issue summary.

The following integration requirements are not a guarantee that every hosted service version, token type, or account plan remains compatible. Check server/API behavior and third-party account policies against the actual deployed versions; these setup requirements do not establish a successful provider retest.

Version-aware sending requires executable version information and corresponding versions/releases in the tracker. Where offered, a four-number match avoids loose matching but requires registering each build. For GitHub/GitLab's Post bugs only for released builds, create the matching releases/tags before expecting reports. Several senders take the project's executable version, not the individual faulting DLL's version; preserve both in your investigation records.

Tracker upgrades, token expiration, permission changes, and revised required fields can break applications already deployed. Before changing the receiving system, submit reports from the oldest application build you still support as well as the current one.

3.7 Custom sending and offline storage are application features

For your own transport, chapter 24 provides the complete custom-sender integration example. The extension point is TELUniversalSender in ESend, overriding SendMessage: TResponse. Register the class before selecting it through CurrentEurekaLogOptions.SenderClasses or adding it with AddSenderClass. Merely assigning an unregistered class name is not enough.

The sender receives AttachedFiles and a copy of the current options in Options. There may be one packed report or multiple files. Fields such as BugID, call stack, application version, user email, and reproduction steps are meaningful when the sender is invoked during exception processing; do not assume a manually constructed sender has all of that context. A successful TResponse must mean the operation you advertise actually completed. Return failure with an appropriate error message/code when it did not, so fallback and recovery remain possible.

EurekaLog's documented failure handling does not include an automatic persistent resend queue. Local .el saving, “copy to My Documents on failure”, and a fallback sender are different things.

The documented offline-storage design is:

1. Implement a sender that copies all outgoing attachments into a report-specific directory before temporary files are removed.
2. Save enough options and metadata to send later. The source example uses params.json containing files and options; Options.Assign copies the sender settings for serialization. Treat this file as sensitive because sender settings can include credentials and private data.
3. Register that storage sender as the only sender, or append it as the final fallback with AddSenderClass. Returning srSent here means stored locally, not delivered remotely; configure user-facing messages accordingly.
4. A separate delivery worker loads the saved options and filenames, creates the intended real sender, assigns AttachedFiles and Options, calls SendMessage, and frees the sender. Delete a queued item only according to the worker's explicitly defined successful-delivery policy.
5. Own the rest of the queue lifecycle: atomic readiness, partial copies, duplicate deliveries, size/age limits, permissions, credentials changing between enqueue and send, retry schedule, uninstall cleanup, and acknowledgement handling. The source example is not a finished implementation of those policies.

Choose a launch mechanism that exists for your application: a service worker, a scheduled process, or an explicit user action. “Try on the next exception” can leave a report stranded forever. A different uploader process also has its own firewall rules, account, proxy configuration, and access to the queue. This is not an option that the book can truthfully turn on with a checkbox.

For a desktop without a custom queue, enable Save bug report copy to My Documents folder on failure and tell the user how to send that copy securely. Copy bug report to clipboard is another manual handoff, not automatic retry, and may expose report data to other software. Neither is a sensible recovery interface for an unattended service.

3.8 Diagnose the stage that actually failed

KnowHow article 72 documents a particularly common partial success: an API creates a small issue first, then fails when uploading the larger report file. Test... may work while the real application fails because the real screenshot, logs, or accumulated report is larger. The reverse is also possible with differently sized test data.

Use chapter 5's internal diagnostic mode to capture the sending stages. Correlate its times with web-server, reverse-proxy, mail, and tracker logs. In an authorized controlled environment, Fiddler or Wireshark can help identify the failing request; a raw encrypted capture does not reveal plaintext by itself. Keep credentials and report contents out of shared traces.

For PHP-based hosting, check upload_max_filesize, post_max_size, max_file_uploads, and memory_limit, as well as the web server/proxy and tracker's own limits. For other stacks, identify the corresponding body/upload/text limits rather than copying PHP values. Increase a limit only after confirming the rejection and choosing a bounded policy. Reducing an unnecessary attachment is often better than accepting unlimited uploads.

3.9 Prove the complete delivery path

Use a disposable test mailbox/project or a private intake directory, not a production user's data. This procedure distinguishes configuration success from actual report delivery.

1. Keep local saving enabled and deletion-after-send disabled. Choose a distinctive test version and record its exact binary and EurekaLog version.
2. In Sending, use Connect where available, then Test.... Locate the actual message, issue, or stored file at the destination. Confirm the selected project and account are the intended ones.
3. Run the application outside the IDE debugger using its real deployment account. Invoke the controlled test exception from chapter 1. Include a harmless marker file through the normal attachment mechanism, if attachments are part of your production design.
4. Retrieve the received .elp/.el/.elx, open it in Viewer, and confirm the application version, exception location, and marker contents. A mail body or tracker summary alone is insufficient.
5. Repeat the same exception. Verify the intended duplicate behavior: count update, attachment retention, and destination. Then close the test issue and repeat to check closed-issue handling. If version-aware reopening is used, test it with a build at or beyond the recorded fixed version.
6. If leak reporting is enabled, test a controlled leak report too; shutdown-time sending has a different runtime context from a desktop button exception.
7. In the controlled environment, make the endpoint unavailable and repeat. Verify that the local copy, fallback, or failure backup actually exists and can be retrieved. Restore connectivity; do not assume old reports resend automatically.
8. Exercise a report near your intended size ceiling and one over it. Check that excessive data produces a visible failure/recoverable local artifact, not an empty ticket presented as complete delivery.
9. Remove the intentional fault from the release build, restore the intended retention/privacy settings, and retain the delivery evidence with the build record. Repeat this check after sender, authentication, hosting, or tracker changes.

Success means the investigator can use the received evidence. Continue with chapter 4. If report generation or EurekaLog's own processing is failing before delivery, use chapter 5.