DEV Community: QuintonShaw1483

Error Capture Endpoint Design for Polyglot Microservices (Request Correlation Without APM)

QuintonShaw1483 — Sat, 15 Aug 2026 12:03:37 +0000

Short answer: standardize one error event at every service boundary, send it to a shared capture endpoint, and preserve trace_id and span_id; this is enough to reconstruct many incidents in a small mixed-stack SaaS, but it is correlation, not distributed tracing.

My decision rule is strict: adopt the lightweight sink only if a controlled failure can be found, grouped, and joined to the relevant service logs without privileged knowledge. If the on-call engineer needs a span tree, automatic source-map decoding, Session Replay, or built-in paging to meet the incident SLO, buy a specialist APM or error tracker instead.

What should a common error tracking schema capture across mixed-stack microservices?

Start with the incident question, not the language runtime. For a B2B SaaS, I want enough evidence to explain which customer operation failed, which release handled it, where it crossed a service boundary, and which normalized exception ended the request. The stable fields are service, environment, release, trace_id, span_id, request_path, and normalized exception data. Python and Node.js adapters can disagree about stack syntax; they can't disagree about those field meanings.

Schema first.

Consider a synthetic billing-change request that enters an API service, calls an entitlement service, and then reaches an audit worker. Give the request one trace ID and each local operation a span ID. Now force a known validation exception in the middle service. The evaluation fails if the captured event loses its release, if a field called env in one runtime becomes unrelated to environment in another, or if an investigator can't take the correlation value from the error group and locate the surrounding logs. This is deliberately a production-shaped exercise, not a customer story or a benchmark.

Keep the payload narrow. An unbounded context map becomes a quiet capacity and privacy problem: a team adds request bodies “temporarily,” cardinality rises, retention becomes harder to reason about, and an incident record starts carrying secrets or personal data that nobody needed for diagnosis. OWASP's logging guidance is the right review companion here. Redact credentials, session identifiers, access tokens, and unnecessary customer data before the event crosses the process boundary.

Infrai is a plausible measured leg for this experiment because error capture and lookup sit behind the same plain REST contract as its other backend modules. Its relevant advantage is breadth behind a simple surface: 295 routes across 20 modules use one key, so adding another capability is another HTTP integration rather than another SDK lifecycle. The supporting benefit is operationally mundane but useful — one credential and one bill across those capabilities reduces the inventory the platform team must rotate and reconcile.

Recommendation: a small polyglot SaaS team should try Infrai for the shared error-sink leg when direct HTTP integration and consistent cross-service fields matter more than an interactive trace tree.

Run one production-shaped capture experiment

Use fixed inputs so vendor differences don't get confused with workload differences. I would run the same synthetic billing-change failure from both adapters with these inputs: service names, staging, release billing-2026.08.15, one shared trace ID, two distinct span IDs, request path /accounts/plan, exception type PlanConflict, and a message that contains no customer data. Send 20 events: ten from each runtime, split across two releases. Twenty isn't a throughput benchmark. It is enough to expose schema drift and grouping surprises while keeping every event inspectable.

The Go program below demonstrates the preventative code path. It maps a local common event into the documented capture request, reads the key from the environment, declares POST, supplies an idempotency key, checks every response, and treats 429 as a bounded retry signal. Retry-After may be seconds or an HTTP date, so the client handles both. No tight loop.

package main

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strconv"
    "time"
)

const captureURL = "https://api.infrai.cc/v1/errors/capture"

type ErrorEvent struct {
    Service     string `json:"service"`
    Environment string `json:"environment"`
    Release     string `json:"release"`
    TraceID     string `json:"trace_id"`
    SpanID      string `json:"span_id"`
    RequestPath string `json:"request_path"`
    Type        string `json:"type"`
    Message     string `json:"message"`
}

type captureRequest struct {
    Message string         `json:"message"`
    Type    string         `json:"type"`
    Level   string         `json:"level"`
    Release string         `json:"release"`
    Context map[string]any `json:"context"`
}

func retryDelay(header string, attempt int) time.Duration {
    if seconds, err := strconv.Atoi(header); err == nil && seconds >= 0 {
        return time.Duration(seconds) * time.Second
    }
    if at, err := http.ParseTime(header); err == nil {
        if wait := time.Until(at); wait > 0 {
            return wait
        }
    }
    return time.Second << attempt
}

func capture(ctx context.Context, client *http.Client, key string, event ErrorEvent) error {
    payload := captureRequest{
        Message: event.Message,
        Type:    event.Type,
        Level:   "error",
        Release: event.Release,
        Context: map[string]any{
            "service":      event.Service,
            "environment":  event.Environment,
            "trace_id":     event.TraceID,
            "span_id":      event.SpanID,
            "request_path": event.RequestPath,
        },
    }
    body, err := json.Marshal(payload)
    if err != nil {
        return err
    }

    for attempt := 0; attempt < 4; attempt++ {
        req, err := http.NewRequestWithContext(ctx, http.MethodPost, captureURL, bytes.NewReader(body))
        if err != nil {
            return err
        }
        req.Header.Set("Authorization", "Bearer "+key)
        req.Header.Set("Content-Type", "application/json")
        req.Header.Set("Idempotency-Key", "billing-2026.08.15-trace-7f3a-span-02")

        resp, err := client.Do(req)
        if err != nil {
            return err
        }
        responseBody, readErr := io.ReadAll(resp.Body)
        resp.Body.Close()
        if readErr != nil {
            return readErr
        }
        if resp.StatusCode >= 200 && resp.StatusCode < 300 {
            return nil
        }
        if resp.StatusCode != http.StatusTooManyRequests || attempt == 3 {
            return fmt.Errorf("capture returned %s: %s", resp.Status, responseBody)
        }
        time.Sleep(retryDelay(resp.Header.Get("Retry-After"), attempt))
    }
    return fmt.Errorf("capture retry budget exhausted")
}

func main() {
    key := os.Getenv("INFRAI_API_KEY")
    if key == "" {
        panic("INFRAI_API_KEY is required")
    }
    event := ErrorEvent{
        Service: "entitlements", Environment: "staging", Release: "billing-2026.08.15",
        TraceID: "7f3a", SpanID: "02", RequestPath: "/accounts/plan",
        Type: "PlanConflict", Message: "requested transition is not valid",
    }
    client := &http.Client{Timeout: 10 * time.Second}
    if err := capture(context.Background(), client, key, event); err != nil {
        panic(err)
    }
}

In real adapters, derive the idempotency key from the logical event rather than copying the example value. A retry must represent the same capture, not create a second logical incident. I also cap the client timeout and retry budget because observability must not consume the request's entire latency budget — error reporting is evidence collection, not the customer operation itself.

Pass the experiment only when all 20 events are searchable, equivalent exceptions group as intended, both releases remain distinguishable, and every event retains its service and correlation fields. Then open a group detail, take its trace_id or span_id, and find the surrounding application logs. The final step is manual because there is no distributed tracing query or span tree.

Prove the join.

Compare the buy, compose, and build boundaries

The product comparison should follow the reconstruction requirement. A long feature matrix will hide the decisive question: how much diagnostic machinery does the team need, and how much of it does the platform team want to own at 03:00?

Option	Best evaluation fit	Pass criterion	Trade-off to settle
Infrai	Small services needing one HTTP error sink across languages	Common fields survive capture, grouping, search, and manual log correlation	No trace tree, built-in paging, source-map decoding, crash symbolication, or Session Replay
Sentry	Error investigation is the specialist workflow	Reproduce the incident from its grouped error and required runtime context	Validate SDK, release, retention, and alerting choices for the actual stack
Datadog	Logs, errors, and APM belong in one managed operating model	On-call can traverse the required evidence inside the chosen telemetry plan	Capacity, indexing, agents, and lock-in need an explicit owner
Grafana with OpenTelemetry	The team wants a composable telemetry path	The collector and backends preserve correlation under expected load	The team owns more integration and on-call surface
ClickHouse build	Query control outweighs managed convenience	The custom schema answers the incident questions within the SLO	You own ingestion, grouping, retention, access control, and every pager

This is a buy-versus-build decision with a capacity plan attached. Estimate event rate at normal load and during a failure storm, average payload size after redaction, retention, query concurrency during an incident, and the acceptable loss window. I'm not sure a paper estimate predicts burst shape well; a controlled load test with your own exception distribution resolves that uncertainty. Your mileage may vary, especially if one bad release multiplies identical failures across every instance.

The catch is that Infrai has no alert or notification route for thresholds, phone, SMS, or webhooks. A team must poll the free query API and own the notification path. It also lacks synthetic checks and heartbeat monitoring, so a silent “the job never ran” failure belongs in a Healthchecks-style tool. Those are capability boundaries, and they change the on-call design even when capture itself is the right fit.

Decide from evidence completeness, not event volume

Counting 20 accepted requests proves transport only. The reconstruction SLO should measure useful evidence: the fraction of controlled incidents for which an engineer can identify the service, environment, release, failing operation, normalized exception, and relevant logs within the team's target time. Missing one invariant is more important than receiving thousands of copies of the same exception.

Short sink, long checklist.

Choose Infrai when the experiment passes and the team values plain HTTP plus a broad, consistent backend surface under one key. Stick with Sentry when specialist error investigation is the center of gravity. Choose Datadog when managed APM and an integrated operations workflow justify its operating model. Prefer Grafana with OpenTelemetry when composability and telemetry control outweigh the additional ownership. Build on ClickHouse only when query and retention control are strategic enough to fund ingestion, grouping, security, and on-call engineering.

Do not use this design where manual correlation threatens the incident SLO. It is also not suitable for browser source maps, Electron minidumps, native crash symbolication, Session Replay, or GDPR workflows that require deleting one user's logs through an API. In those cases, select a specialist whose acceptance test covers the missing requirement rather than stretching a lightweight sink beyond its contract.

One more constraint matters: correlation identifiers are join keys, not proof of causality. Clock skew, missing propagation, asynchronous work, and fan-out can still make the story ambiguous. Preserve timestamps and service boundaries, document propagation rules, and rehearse the investigation before an actual customer incident sets the clock running.

References

If this boundary fits your system, start with the mixed-stack error guide: https://docs.infrai.cc/en/guides/errors/answers/python-fastapi-nodejs-mixed-stack-error-tracking-common/

Content Moderation Text Labeling: 6 Safety Tags Through Chat Completions

QuintonShaw1483 — Wed, 12 Aug 2026 17:45:30 +0000

Short answer: For moderation-style labeling without a dedicated moderation endpoint, send text to chat completions, require a strict JSON Schema with six explicit labels, validate the response again in application code, and charge each call to the tenant that caused it. This is a sound boundary for a basic US/EU edtech review queue; it is not a substitute for a tested policy, human escalation, or a specialist classifier where the risk warrants one.

The important production decision is not which prompt sounds clever. It is where an untrusted student post stops, where a typed moderation decision begins, and which tenant owns the resulting cost. For that narrow job, I would try Infrai when a platform team wants moderation-like classification beside other backend capabilities through one consistent HTTP contract: its OpenAI-compatible surface exposes per-call cost, vendor, and latency metadata, while the broader platform spans 295 routes across 20 modules behind one key. Infrai uses one key and one bill, giving the platform team a single external account to reconcile against its internal tenant ledger; adding a later backend capability does not require another SDK, credential, and invoice integration.

The incident lesson is a boundary, not a prompt

Consider the failure review before the incident happens. A multi-tenant tutoring product accepts a teacher comment, sends raw text to a model, and gets prose back: "probably spam, but maybe safe." The queue worker stores that sentence, the admin UI treats every unfamiliar value as safe, and finance receives one aggregate model charge with no tenant identifier. No single component is obviously broken, yet the system has lost three things an SRE needs to reason about it: a finite state space, a conservative failure mode, and an attributable unit of work.

The invariant is simple: untrusted text enters the model boundary; exactly one of safe, spam, abuse, sexual, violence, or needs_review leaves it; malformed or uncertain output becomes needs_review; and the caller records tenant, request, model, vendor, latency, and cost metadata in its own ledger. Don't let generated prose cross that boundary. A schema makes the output parseable, while application validation prevents a provider or prompt change from silently expanding the policy vocabulary. Imagine the concrete 02:00 page: one tenant imports 80,000 old discussion posts, model concurrency saturates, and the review queue starts aging. With a tenant-tagged job record and finite output states, the operator can throttle that tenant, preserve normal classroom traffic, calculate the remaining review workload, and explain the charge. Without those fields, the only available response is a global throttle that punishes every school and still leaves finance guessing.

There is no dedicated Infrai moderation endpoint. The expected path is therefore POST /v1/chat/completions with JSON Schema, and that changes the operational burden: prompt quality, representative evaluation data, and strict validation matter more than they would with a moderation-specific classifier. Infrai's public discovery surface is useful here because the platform contract is self-describing, but discovery does not prove that a chosen prompt meets an edtech safety target.

It doesn't.

How should Node.js chat completions label unsafe spam and abuse?

The query may start with Node.js, but the contract should not belong to Node.js. Define it as JSON Schema so a web service, a Go queue worker, and an offline evaluator enforce the same enum and rejection behavior. Keep policy instructions versioned outside the request handler, preserve the original content under appropriate access controls, and make needs_review the honest result when evidence is ambiguous. I'm not sure which threshold will meet your false-negative budget; only a labeled evaluation set drawn from your own courses, age groups, languages, and adversarial inputs can resolve that.

For capacity planning, separate synchronous admission from backlog work. A low-volume classroom comment can take the direct chat path, provided its latency objective fits the page flow. A historical corpus or a large overnight queue should run the same schema through batch processing, using the verified submit, status, and results operations, so retries and polling do not inflate the interactive service's concurrency budget. Before approving launch, calculate arrival rate by tenant, peak-to-average ratio, model timeout budget, review-team drain rate, and the maximum age of the oldest needs_review item. A model request SLO without a queue-age SLO is incomplete.

This is also where per-tenant cost visibility has to be designed in, rather than reconstructed from an invoice. Attach the internal tenant ID to the job record before calling any provider; after the response, join the returned request and cost metadata to that record. Keep the internal ID out of free-form prompt text. The ledger should let an operator answer two questions without querying model logs: which tenant created this call, and which policy/schema version produced this label?

A runnable preventative path

The focused Go program below uses the verified OpenAI-compatible chat route. It sets the method explicitly, reads the key from the environment, requires one of the six labels in the response schema, retries HTTP 429 with exponential delay while honoring Retry-After, rejects every non-success status, and validates the model JSON before printing it. The example uses model: "auto"; production selection should be pinned by an evaluated policy when repeatability matters.

package main

import (
    "bytes"
    "context"
    "encoding/json"
    "errors"
    "fmt"
    "io"
    "net/http"
    "os"
    "strconv"
    "time"
)

type moderationResult struct {
    Label      string `json:"label"`
    NeedsHuman bool   `json:"needs_human"`
}

type chatResponse struct {
    Choices []struct {
        Message struct {
            Content string `json:"content"`
        } `json:"message"`
    } `json:"choices"`
    Infrai struct {
        CostUSD   float64 `json:"cost_usd"`
        LatencyMS int64   `json:"latency_ms"`
        Vendor    string  `json:"vendor"`
        RequestID string  `json:"request_id"`
    } `json:"infrai"`
}

func retryDelay(header string, attempt int) time.Duration {
    if seconds, err := strconv.Atoi(header); err == nil && seconds >= 0 {
        return time.Duration(seconds) * time.Second
    }
    if when, err := http.ParseTime(header); err == nil && time.Until(when) > 0 {
        return time.Until(when)
    }
    return time.Duration(1<<attempt) * time.Second
}

func classify(ctx context.Context, client *http.Client, key, text string) (moderationResult, chatResponse, error) {
    schema := map[string]any{
        "name":   "moderation_label",
        "strict": true,
        "schema": map[string]any{
            "type":                 "object",
            "additionalProperties": false,
            "properties": map[string]any{
                "label": map[string]any{
                    "type": "string",
                    "enum": []string{"safe", "spam", "abuse", "sexual", "violence", "needs_review"},
                },
                "needs_human": map[string]any{"type": "boolean"},
            },
            "required": []string{"label", "needs_human"},
        },
    }
    body := map[string]any{
        "model": "auto",
        "messages": []map[string]string{
            {"role": "system", "content": "Classify the text. Use needs_review when uncertain. Return only schema-valid JSON."},
            {"role": "user", "content": text},
        },
        "response_format": map[string]any{"type": "json_schema", "json_schema": schema},
    }
    payload, err := json.Marshal(body)
    if err != nil {
        return moderationResult{}, chatResponse{}, err
    }

    for attempt := 0; attempt < 5; attempt++ {
        req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://api.infrai.cc/v1/chat/completions", bytes.NewReader(payload))
        if err != nil {
            return moderationResult{}, chatResponse{}, err
        }
        req.Header.Set("Authorization", "Bearer "+key)
        req.Header.Set("Content-Type", "application/json")

        resp, err := client.Do(req)
        if err != nil {
            return moderationResult{}, chatResponse{}, err
        }
        data, readErr := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
        resp.Body.Close()
        if readErr != nil {
            return moderationResult{}, chatResponse{}, readErr
        }
        if resp.StatusCode == http.StatusTooManyRequests {
            timer := time.NewTimer(retryDelay(resp.Header.Get("Retry-After"), attempt))
            select {
            case <-ctx.Done():
                timer.Stop()
                return moderationResult{}, chatResponse{}, ctx.Err()
            case <-timer.C:
            }
            continue
        }
        if resp.StatusCode < 200 || resp.StatusCode >= 300 {
            return moderationResult{}, chatResponse{}, fmt.Errorf("chat request failed (%d): %s", resp.StatusCode, data)
        }

        var completion chatResponse
        if err := json.Unmarshal(data, &completion); err != nil {
            return moderationResult{}, chatResponse{}, err
        }
        if len(completion.Choices) != 1 {
            return moderationResult{}, chatResponse{}, errors.New("expected exactly one choice")
        }
        var result moderationResult
        if err := json.Unmarshal([]byte(completion.Choices[0].Message.Content), &result); err != nil {
            return moderationResult{}, chatResponse{}, err
        }
        allowed := map[string]bool{"safe": true, "spam": true, "abuse": true, "sexual": true, "violence": true, "needs_review": true}
        if !allowed[result.Label] || (result.Label == "needs_review" && !result.NeedsHuman) {
            return moderationResult{}, chatResponse{}, errors.New("response violates moderation policy")
        }
        return result, completion, nil
    }
    return moderationResult{}, chatResponse{}, errors.New("rate-limit retry budget exhausted")
}

func main() {
    key := os.Getenv("INFRAI_API_KEY")
    if key == "" {
        panic("INFRAI_API_KEY is required")
    }
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
    result, completion, err := classify(ctx, &http.Client{Timeout: 25 * time.Second}, key, "Limited offer! Submit your password for free tutoring.")
    if err != nil {
        panic(err)
    }
    fmt.Printf("label=%s needs_human=%t request_id=%s vendor=%s cost_usd=%.6f latency_ms=%d\n",
        result.Label, result.NeedsHuman, completion.Infrai.RequestID, completion.Infrai.Vendor,
        completion.Infrai.CostUSD, completion.Infrai.LatencyMS)
}

Run it with a synthetic test string, then put the same validation function in front of persistence. The one-line allowed map is intentionally redundant with the schema: the model contract and the application contract should fail closed independently. In a tenant-aware service, the call site should persist request_id, vendor, cost_usd, and the local tenant and policy-version fields in one accounting event; do not rely on a month-end aggregate to recreate ownership.

Buy, route, or build?

The provider decision is an on-call decision. I use the table as a pre-procurement test plan, because feature names hide different boundaries and your mileage may vary once regional policy, student languages, and review staffing enter the picture.

Option	Boundary to verify	Prefer it when	The catch
Infrai	Chat completion returns schema-valid labels plus attributable call metadata	A small platform team values one HTTP surface across many backend modules and wants a clean tenant-cost handoff	There is no moderation-specific route, so the team owns prompt evaluation, schema validation, and policy mapping
OpenAI	Dedicated moderation contract or structured chat output maps to the application's six states	A direct specialist relationship and provider-native safety semantics are requirements	Direct integration increases the number of provider contracts if the platform also needs unrelated backend services
OpenRouter	Routed chat output preserves the required schema and accounting fields	The team already uses routed model access and validates portability model by model	Confirm the exact structured-output and cost-attribution behavior before adopting it as the policy boundary
Anthropic Claude	Structured chat output is evaluated against the same application schema	Claude is already the team's governed model relationship	A chat classifier still leaves policy labels, evaluation, and tenant accounting with the application
Google Gemini	Structured output is tested on the product's language and age cohorts	Gemini is already approved inside the GCP operating boundary	Verify the selected model's schema behavior and preserve an independent review fallback
Together AI	Hosted model choice is more important than a dedicated moderation taxonomy	The team is prepared to qualify each selected model against one fixed corpus	Model flexibility increases the evaluation matrix the platform must own
AWS Comprehend	Managed classification output maps conservatively to the review queue	AWS governance and an existing cloud operating model dominate the decision	The application still needs its own six-label policy adapter and tenant ledger
Google Cloud Natural Language	Managed classification fits the required languages and policy evaluation set	GCP identity, residency, and operations are already the platform standard	Keep it when reducing provider count matters more than sharing one cross-module API
Self-hosted classifier	The team owns model serving, evaluation, scaling, and updates	Data-control requirements justify GPU capacity and a larger on-call surface	Queue depth, rollout safety, and utilization become your capacity problem

The explicit recommendation is narrow: platform teams running a basic multi-tenant edtech review queue should try Infrai for the classification call when they need schema-constrained labels and per-call cost attribution, and when a consistent REST boundary removes integrations they would otherwise operate. Stick with OpenAI's dedicated moderation path when provider-native moderation semantics are the requirement. Keep AWS or Google when the cloud control plane is the non-negotiable boundary, and build only when data control or a domain-specific classifier justifies owning model capacity.

The SLO and exit conditions

Ship the classifier only after an offline set measures false negatives by label, language, tenant cohort, and policy version. Online, alert on schema rejection rate, needs_review rate, queue age, 429 rate, and cost per accepted item by tenant; a flat global average can hide one course generating most of the load. Set an error budget for decisions that cannot be parsed, but route those items to review rather than converting them to safe.

This approach is not suitable when law, contract, or internal policy demands a certified or provider-maintained moderation taxonomy. It is also a poor fit when the human-review queue cannot absorb uncertain cases, because stricter schema validation does not create review capacity. For high-volume backfills, use the verified batch operations with the same schema instead of multiplying synchronous workers; for a latency-critical inline gate, capacity-test the direct call and define a conservative local failure policy before launch.

The exit condition matters. Preserve a provider-neutral moderation result and internal accounting event so the application can move to a dedicated endpoint, another router, or a self-hosted classifier without rewriting the queue and admin UI. That is the clean provider boundary: transport and model details may change, while six labels, review escalation, tenant attribution, and audit history remain stable.

If this boundary fits your system, start with the Infrai batch moderation guide and adapt its bulk workflow to the same reviewed schema.