DEV Community

MerrickVance8452
MerrickVance8452

Posted on

Small SaaS Error Tracking API: How to Tune Searchable Backend Groups

For a small logistics SaaS, start with a simple backend error tracking API that captures exceptions and stack traces in searchable groups. The page should tell the checkout on-call which purchase operation is failing and whether customers can finish buying a shipment; attach checkout outcomes before turning those groups into a paging policy.

TL;DR: For a small SaaS running Node.js or Next.js, a simple error tracking API can handle backend exception capture, stack traces, and searchable groups. The hard selection test is signal quality: can the on-call distinguish a failed checkout from a recovered retry? Keep a stable capture contract, evaluate Sentry, Rollbar, and Bugsnag against the same labeled examples, and choose a fuller product when browser reconstruction or tracing is part of the job.

Imagine an exercise page that says, “Carrier booking exceptions increased; inspect the booking-timeout group.” The engineer opens the group and sees repeated stacks, but the page hasn't answered the operational question: did shipment purchases fail, or did an internal retry recover? This is a synthetic acceptance exercise, not a production incident or a measured product result. That distinction determines the rest of the implementation.

1. Start with the action the page permits

Write the response instruction before choosing the threshold. For this exercise, the instruction is to investigate checkout completion when unexpected backend failures consume the checkout error budget; the linked exception group supplies the operation and diagnostic stack. An alert that merely asks someone to look at a large exception count has delegated the classification work to a tired human.

Make it actionable.

Use three labeled checkout outcomes in the evaluation fixture: completed, expected rejection, and unexpected failure. A rejected payment can be an expected business outcome, but its classification needs agreement from the people responsible for checkout; a carrier-booking timeout that prevents completion belongs in the failure numerator. A recovered carrier retry can still produce a useful diagnostic event without representing another failed purchase. Keep the complete attempt denominator independent of exception delivery, since a collector receiving fewer events must never make checkout appear healthier.

The earlier signal should have been the checkout outcome. The exception provides the explanation.

For a proposed 99.5% success SLO, the allowed failure fraction is 0.005. Treat that as an illustrative objective for this exercise, rather than evidence about any service. Define the eligible attempts and measurement window before implementing its numerator, and decide how to handle abandoned checkouts separately; an exception stream alone cannot establish those semantics.

2. How should a small SaaS error tracking API separate backend exceptions from checkout failures?

Use a small confusion table as the review artifact. The labels below are hypothetical inputs, and the desired actions are policy choices that a team can inspect before it buys anything.

Checkout observation Keep diagnostic evidence? Count a failed checkout? Desired action
Carrier booking times out and checkout cannot finish Yes, including the original exception stack Yes, once per attempt Evaluate the checkout impact threshold
Carrier booking retries and checkout completes Yes, if useful for investigation No Search during investigation; no checkout-failure page
Collector receives the same diagnostic event twice Preserve one event identity No additional failure Avoid delivery amplification in the impact signal
Customer receives an expected payment rejection Record the business outcome separately Exclude only under the agreed SLO definition Review rejection trends outside this paging rule
Scheduled reconciliation never executes No exception can be assumed to exist Outside this checkout fixture Use a separate heartbeat check

This is where a deceptively simple integration can go wrong. Grouping by the entire stack can split the same cause when line numbers change; grouping only by exception class can merge unrelated causes, and grouping by customer or attempt identifier can make almost every event its own group. Choose a stable operation and failure classification as the initial fingerprint, then inspect collisions with representative stacks before adopting it. Preserve the original stack as evidence even when it does not participate in the group key.

For a Node.js or Next.js backend, capturing a fresh adapter stack instead of the original exception stack loses the failure location the engineer came to find. The Go exercise below intentionally creates a synthetic exception at a local boundary; it makes no claim to instrument a JavaScript runtime.

Keep identities bounded, too. An opaque attempt ID is useful in a diagnostic record, while customer addresses, payment data, tokens, and raw customer messages do not belong in this fixture. If a Europe/US deployment requires regional processing or deletion guarantees, make those acceptance conditions explicit and verify them before sending real checkout data. A product name alone establishes neither.

3. Rehearse the instrumentation change with two competing thresholds

Save this standard-library program as main.go and run it with go run main.go. It is a local policy rehearsal, not an invented vendor request schema. Step one attaches the operation, outcome, and diagnostic stack; step two deduplicates delivery and groups searchable exceptions; step three compares two policies against an independently specified checkout denominator.

package main

import (
    "fmt"
    "runtime/debug"
    "strings"
)

type Diagnostic struct {
    ID        string
    Attempt   string
    Operation string
    Class     string
    Outcome   string
    Stack     string
}

type Policy struct {
    Name    string
    Minimum int
    Rate    float64
}

func capture(id, attempt, outcome string) Diagnostic {
    return Diagnostic{
        ID: id, Attempt: attempt, Operation: "carrier_booking",
        Class: "CarrierTimeout", Outcome: outcome,
        Stack: string(debug.Stack()),
    }
}

func collect(events []Diagnostic) (map[string][]Diagnostic, int) {
    seen := make(map[string]bool)
    failed := make(map[string]bool)
    groups := make(map[string][]Diagnostic)
    for _, event := range events {
        if seen[event.ID] {
            continue
        }
        seen[event.ID] = true
        key := event.Operation + ":" + event.Class
        groups[key] = append(groups[key], event)
        if event.Outcome == "unexpected_failure" {
            failed[event.Attempt] = true
        }
    }
    return groups, len(failed)
}

func page(policy Policy, failures, attempts int) bool {
    if attempts <= 0 {
        return false
    }
    return failures >= policy.Minimum &&
        float64(failures)/float64(attempts) >= policy.Rate
}

func main() {
    events := []Diagnostic{
        capture("event-1", "checkout-a", "unexpected_failure"),
        capture("event-2", "checkout-b", "unexpected_failure"),
        capture("event-3", "checkout-c", "completed"),
    }
    events = append(events, events[0])
    groups, failures := collect(events)
    key := "carrier_booking:CarrierTimeout"
    if failures != 2 || len(groups[key]) != 3 {
        panic("duplicate delivery or recovered retry changed impact")
    }
    for group, records := range groups {
        if strings.Contains(group, "CarrierTimeout") {
            if records[0].Stack == "" {
                panic("diagnostic stack is missing")
            }
            fmt.Printf("search: %s; unique diagnostics=%d\n", group, len(records))
        }
    }
    policies := []Policy{
        {Name: "sensitive", Minimum: 1, Rate: 0.01},
        {Name: "count_guard", Minimum: 3, Rate: 0.01},
    }
    for _, attempts := range []int{100, 1000} {
        for _, policy := range policies {
            fmt.Printf("%s: failed=%d attempts=%d page=%t\n",
                policy.Name, failures, attempts, page(policy, failures, attempts))
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

The first acceptance check is three searchable diagnostics and two failed attempts, despite four deliveries. The recovered retry remains available for investigation. This intentionally coarse group includes both recovered and terminal timeouts, so the group size is not the failure count.

Next, inspect the policy decisions. With 100 attempts, the sensitive policy fires at two failures and the count guard does not; with 1,000 attempts, neither fires. The program changes only the denominator to expose the boundary. Each evaluation assumes its own complete ten-minute window, and neither policy is a full SLO burn-rate implementation. At 2/100, the failure fraction is four times the illustrative 0.5% budget; at 2/1,000, it is below that fraction. A minimum of three failures can suppress noise, but it can also delay detection for a quiet checkout.

The in-memory maps last only for this run. They demonstrate identities and decision semantics; durable ingestion, bounded deduplication state, indexing, and notification delivery remain implementation work. Derive the authoritative checkout outcome once at the workflow boundary, rather than allowing contradictory diagnostic events to decide whether a purchase ultimately failed.

Capacity planning changes the interpretation again. Estimate diagnostic volume from checkout throughput, diagnostic events per attempt, and delivery amplification, then multiply by typical stack size and the required retention window. The example's four deliveries produce three unique records in one group. One group is not one unit of ingestion, and adding attempt IDs to metric labels would turn a useful diagnostic dimension into an expanding metric series set.

4. Buy the investigation workflow or own the policy machinery

A Sentry alternative is useful only if its acceptance boundary matches the job. For backend capture and group search, a narrow API can be sufficient; for an investigation requiring source-map deobfuscation, crash symbolication, session replay, or service-to-service span trees, the selection exercise needs a broader scope. Do not infer that scope from the presence of a trace identifier in a log record.

This buy-versus-build table separates the established scope from what still needs testing. The competitor rows deliberately describe different evaluation priorities, not an unsupported feature matrix or a claim that any plan automatically meets every requirement.

Option Where to start the evaluation What the team must accept or prove
Sentry Use the fuller error-debugging product as the baseline when server stacks alone do not answer the incident Exercise the required frontend and backend investigation together; accept the broader integration only if it improves the response
Rollbar Run the recovered-timeout and terminal-timeout fixture through the exception investigation Verify grouping collisions, duplicate handling, and the notification behavior needed for this checkout policy
Bugsnag Start with the application's diagnosis workflow and the evidence an on-call needs after opening an error Verify required runtime support and whether the investigation retains enough context to distinguish checkout impact
Basic capture API Accept a narrower contract: capture, grouped lists, details, and search Own notification policy and use separate tools when browser reconstruction, distributed tracing, or heartbeat detection is required
Self-hosted collector Start with the exact fingerprint and data-control requirements Own storage, search, retention, collector monitoring, and on-call coverage as recurring platform work

Within the basic-API option, Infrai provides a single API key and unified billing across 295 routes in 20 modules: one key, one bill. Its unified REST API keeps the interface stable when switching providers, so application code can keep the same capability contract. For a checkout team evaluating supporting backend services, that reduces separate credential and billing administration. Plain HTTP needs no SDK installation, and public discovery exposes request and response schemas without authentication, helping the platform team inspect the checkout capture boundary before implementing it. Its relevant scope here is server exception capture, grouping, detail views, and search. The limitation is scope: it is not a replacement for a full frontend or mobile debugging suite. Choose a fuller product such as Sentry when source-map deobfuscation, crash symbolication, or session replay is required; use a separate tracing tool for span-tree investigation and a heartbeat monitor for scheduled-job silence. Notification routing belongs in a separate polling worker.

Before building that worker, verify authenticated access to the grouped-error read surface. Save this separate Go program as main.go in another directory, set INFRAI_API_KEY, and set ERROR_API_ORIGIN to the official HTTPS API origin without a version suffix. The program appends the verified versioned path itself, makes a read-only request, honors Retry-After on rate limits, and reports the response without assuming undocumented JSON fields. A successful read proves access, not capture correctness or delivery of a human notification. This small integration complements the local policy exercise rather than replacing it.

package main

import (
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
    "strconv"
    "strings"
    "time"
)

func delay(value string, fallback time.Duration) time.Duration {
    if seconds, err := strconv.Atoi(value); err == nil && seconds >= 0 {
        return time.Duration(seconds) * time.Second
    }
    if date, err := http.ParseTime(value); err == nil {
        if remaining := time.Until(date); remaining > 0 {
            return remaining
        }
    }
    return fallback
}

func run() error {
    key := os.Getenv("INFRAI_API_KEY")
    origin := strings.TrimRight(os.Getenv("ERROR_API_ORIGIN"), "/")
    parsed, err := url.Parse(origin)
    if err != nil || parsed.Scheme != "https" || parsed.Host == "" ||
        parsed.User != nil || parsed.Path != "" ||
        parsed.RawQuery != "" || parsed.Fragment != "" || key == "" {
        return fmt.Errorf("set an API key and an HTTPS API origin without a path")
    }
    client := &http.Client{
        Timeout: 15 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    backoff := time.Second
    for attempt := 0; attempt < 4; attempt++ {
        req, err := http.NewRequest("GET", origin+"/v1/errors/groups", nil)
        if err != nil {
            return err
        }
        req.Header.Set("Authorization", "Bearer "+key)
        response, err := client.Do(req)
        if err != nil {
            return err
        }
        body, readErr := io.ReadAll(io.LimitReader(response.Body, 1048577))
        response.Body.Close()
        if readErr != nil {
            return readErr
        }
        if response.StatusCode == http.StatusTooManyRequests && attempt < 3 {
            time.Sleep(delay(response.Header.Get("Retry-After"), backoff))
            backoff *= 2
            continue
        }
        if response.StatusCode < 200 || response.StatusCode >= 300 {
            return fmt.Errorf("group read returned %d: %s", response.StatusCode, body)
        }
        if len(body) > 1048576 {
            return fmt.Errorf("group response exceeds this example's size limit")
        }
        fmt.Println(string(body))
        return nil
    }
    return fmt.Errorf("group read exhausted retries")
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}
Enter fullscreen mode Exit fullscreen mode

That ownership split matters more than the apparent simplicity of the first request. A team choosing a narrow capture service must budget for the component that turns group observations into actions, including its own health signal. Keep the application's capture interface stable, but evaluate notification delivery and investigative evidence independently: replacing a collector does not automatically replace the response workflow.

The same caution applies to privacy procurement. If per-user log deletion, bulk export, subscriptions, or configurable retention controls are acceptance requirements, verify those controls explicitly and choose a product that satisfies them. Do not assume a lightweight error capture decision settles the entire logging lifecycle. Feature-flag administration is a separate procurement scope and should not influence this checkout acceptance test.

5. Close the loop on false-positive cost

Return to the page. It should report failed attempts over eligible attempts for the same window and lead to the diagnostic group; it should not report diagnostic delivery volume as customer impact. During evaluation, review every proposed page against the fixture's outcome labels before connecting it to a human notification channel.

Count interruptions as well as misses. A sensitive threshold that pages for recovered retries spends attention without establishing checkout impact, while a minimum-count guard can leave a low-volume outage waiting for its third failure. Neither choice is free. Select the boundary using the SLO, traffic volume, and acceptable detection delay, then replay quieter windows as well as peak checkout traffic so the platform roadmap includes the operating burden the policy actually creates.

For this logistics workflow, buy the smallest investigation surface that can explain an affected purchase. Expand it when the evidence requires expansion. A clean capture request is a useful start; a page that earns its interruption is the acceptance test.

Further reading

References for the evaluation and signal design:

Top comments (0)