Kdesktop 1264 implement sentry transaction.

[herve-er]

PerformanceTrace (PTrace) Integration for Enhanced Monitoring 🚀

The PerformanceTrace (PTrace) system is designed to track the execution time of various parts of our codebase and send performance data to Sentry for analysis. This enables monitoring, troubleshooting, and optimization the application.

---

How PerformanceTrace Works 📜

Manual PerformanceTrace (Not Recommended in Most Cases 🛑 )

In sentryhandler.h, the enum PTraceName defines all the traceable steps, such as:

• PTraceName::Sync
• PTraceName::UpdateDetection1
• PTraceName::UpdateUnsyncedList, and others.

To minimize the impact in codebase readability due to performance monitoring, pTrace details are defined in the constructor of the SentryHandler::PTraceInfo structure.

Although SentryHandler::PTraceInfo is used exclusively within SentryHandler, it must be updated whenever a new trace is added. This structure provides the following:

• Readable titles and descriptions for display on the Sentry dashboard.
• Automatic management of parent/child relationships between PTraces.

Example implementation in the constructor:

SentryHandler::PTraceInfo::PTraceInfo(SentryHandler::PTraceName pTraceName) {
    _pTraceName = pTraceName;
    switch (_pTraceName) {
        case SentryHandler::PTraceName::Sync:
            _pTraceTitle = "Synchronization";
            _pTraceDescription = "Handles synchronization process.";
            break;
        case SentryHandler::PTraceName::UpdateDetection1:
            _pTraceTitle = "Update Detection 1";
            _pTraceDescription = "Computes file system operations.";
            _parentPTraceName = SentryHandler::PTraceName::Sync;
            break;
        case SentryHandler::PTraceName::UpdateUnsyncedList:
            _pTraceTitle = "Update Unsynced List";
            _pTraceDescription = "Updates the list of unsynced items.";
            _parentPTraceName = SentryHandler::PTraceName::UpdateDetection1;
            break;
        // Additional cases...
    }
}

This setup enables child PTraces to be started automatically as children of their respective parent traces without requiring explicit management of parent IDs by the caller (see below).

Example of Manual PTrace Management:

void synchronize() {
    SentryHandler::startPTrace(SentryHandler::PTraceName::Sync, syncDbId());
    computeFsOp();
    SentryHandler::stopPTrace(SentryHandler::PTraceName::Sync, syncDbId());
}

void computeFsOp() {
    auto pTraceId = SentryHandler::startPTrace(SentryHandler::PTraceName::UpdateDetection1, syncDbId());  
    updateUnsyncedList();
    SentryHandler::stopPTrace(pTraceId); // Same as SentryHandler::stopPTrace(SentryHandler::PTraceName::UpdateDetection1, syncDbId()); 
}

void updateUnsyncedList() {
    auto pTraceId = SentryHandler::startPTrace(SentryHandler::PTraceName::UpdateUnsyncedList, syncDbId());  
    // Perform operations...
    SentryHandler::stopPTrace(pTraceId); // Same as SentryHandler::stopPTrace(SentryHandler::PTraceName::UpdateUnsyncedList, syncDbId());  
}

---

Scoped PerformanceTrace (Recommended in Most Cases ✅ 🦺 )

The SentryHandler::ScopedPTrace class simplifies performance tracing by ensuring that traces are always stopped properly, avoiding:

1. Memory leaks for orphaned transactions.
2. Discarded traces for parented transactions (automatically deleted when the parent terminates but not send to sentry).

When a SentryHandler::ScopedPTrace object is destroyed, its associated trace is automatically stopped.

Constructor Options:

1. Start a new trace using a PTraceName and a syncDbId.
2. Attach to an existing trace using its pTraceId.

Optional: A manualStopExpected flag (default: false). If set to true, the trace must be stopped manually using stop() before the object is destroyed. Otherwise, the trace is marked as aborted, which is helpful for identifying problematic steps on the Sentry dashboard.

Example Usage:

1. Without Manual Stop:

void func1() {
    auto perfMonitor = SentryHandler::ScopedPTrace(SentryHandler::PTraceName::func1, syncDbId());
    // Perform operations...
}

2. With Manual Stop:

void func2() {
    auto perfMonitor = SentryHandler::ScopedPTrace(SentryHandler::PTraceName::func2, syncDbId(), true);
    if (!foo()) {
        // On failure, the trace is marked as aborted.
        return;
    }
    perfMonitor.stop(); // Explicit stop on success.
}

Additional Features:

• SentryHandler::ScopedPTrace::stopAndStart Method: Stops the current trace and starts a new one with the provided parameters (same as ScopedPTrace constructor).
• SentryHandler::ScopedPTrace::stop(true) can be call with the aborted set to true wich will force the pTrace to an aborted state.

---

Tracing Outside Synchronization

A PTrace or ScopedPTrace can be started outside the synchronization context by passing -1 for the syncDbId argument.

---

⚠️ Limitations

1. A PTraceName can only be started once per syncDbId. (asserted in debug mode, ignored in release).

---

Sentry Dashboard 📊

The Sentry dashboard automatically processes PTraces to provide meaningful insights:

Trace Breakdown

Example: Breakdown of a specific sync operation.

Performance Statistics

For each PTrace, we get metrics like median time (P50), P75, and P90 durations, along with other insights:

---

Benefits of PTrace

This system provides invaluable data for:

1. Tracking performance during the upcoming optimization phase.
2. Identifying and addressing regressions in performance.

[ClementKunz]

Can you briefly explain in comment what in a transaction and what is a span in Sentry context?

[ClementKunz]

Perhaps this could be defined in SentryHandler instead to avoid increasing the size of SyncPalWorker class

[ClementKunz]

Could we delegate this logic to the SentryHandler::ScopedPTrace class? The goal should always to add as less as possible into the caller method. LocalFileSystemObserverWorker is already quite complicated

[herve-er]

What about this: 0a60107

[ClementKunz]

Same as above

[herve-er]

#403 (comment)

[sonarcloud]

Quality Gate passed

Issues
1 New issue
2 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud