Node.js Agent 遙測如何平衡錯誤追蹤、結構化日誌與關聯 ID

Short answer: for a Node.js SaaS running AI agent loops, send actionable exceptions to error tracking, write structured logs for the full execution story, and put one correlation ID in both so latency and token cost can be investigated without turning every retry into an alert.

The operational constraint is signal quality. An agent can make several model and tool calls before it answers, so a single user request may produce many slow or failed attempts while still ending successfully. Capturing every attempt as an exception creates noise; keeping only a final exception hides the path that made the request expensive. The useful split is based on the question each signal answers, not on which transport is easiest to add.

This is the choice: error tracking owns failures that require triage, while structured logging owns ordered evidence about attempts, decisions, latency, and usage. Correlation makes them one investigation.

How should a Node.js SaaS use error tracking, structured logs, and correlation IDs?

Use error tracking when an exception crosses an operational boundary: the agent loop cannot produce an acceptable response, a tool contract is violated, or a background job exhausts its retry policy. The event should preserve the exception type, stack, release identifier, and a small set of stable dimensions such as operation name. It should also carry the correlation ID, but not an entire prompt or tool payload. Use structured logs for events that explain normal and abnormal execution: loop start, model-call completion, tool selection, retry, validation outcome, and loop completion. Give every event a consistent schema. For this scenario, useful fields include event_name, correlation_id, trace_id, agent_run_id, attempt, duration_ms, input_tokens, output_tokens, outcome, and error_type. A retry is usually a log event. The exception that survives the retry budget is usually an error-tracking event. Finally, use a correlation ID as a join key across HTTP handling, the agent runner, queued work, and both destinations. If distributed tracing already exists, the W3C traceparent format provides a standard trace context; don't create a second unrelated identity and expect responders to reconcile the two at 2 a.m. A separate business identifier such as agent_run_id can still be useful because one logical run may outlive or span transport-level operations.

That distinction matters. Correlation IDs connect records, but they don't replace the timing and parent-child relationships in a trace.

The boundary is actionability, not severity labels

The simple approach is to call every unsuccessful model or tool attempt an error. It looks comprehensive in a notebook. In production it causes three distortions: expected retries inflate failure counts, repeated captures fragment one incident into many events, and teams begin ignoring alerts that no longer imply user impact. Labeling the same attempts warning instead doesn't solve the data-model problem.

Start from the final state of the agent run. If a transient timeout is retried and the run succeeds, record the attempt in structured logs with its duration and token usage. If the loop stops because its deadline, retry budget, or output contract cannot be satisfied, capture the terminal exception once and link it to those attempts. This preserves the evidence needed to ask, "Why did this run take 8.4 seconds and consume four model calls?" without claiming that every internal branch deserves a page.

The catch is that terminal-only tracking is not suitable when an intermediate failure itself represents a security event, data-integrity risk, or breached service-level objective. In those cases, create a distinct actionable event even if a fallback later succeeds. Conversely, stick with logs rather than an error tracker for high-volume audit history, per-token accounting, and routine latency analysis; exception grouping and triage workflows are the wrong shape for those jobs.

There isn't one universal retry threshold. I'm not sure what failure budget fits your users, and neither a logging library nor an error tracker can decide it. Resolve that uncertainty with an eval set that represents your real tool mix, then choose the point where extra attempts stop improving task success enough to justify their latency and token cost.

A focused event contract for an agent loop

Keep the contract small enough that application code can emit it consistently. The table below separates ownership before implementation details blur it.

An error object should not become the schema. Normalize it at the boundary: stable error type, safe message, stack where appropriate, operation, and IDs. OWASP's logging guidance recommends excluding or masking data such as access tokens, passwords, sensitive personal data, and other secrets. That warning is especially important for AI applications because prompts and tool arguments can contain user text that was never intended for an observability store.

Redact before export.

Node.js AsyncLocalStorage can carry request-scoped context through asynchronous operations. Initialize the context at ingress, copy the standard trace context when present, and explicitly propagate the required identifiers through queue messages. Treat inbound correlation values as untrusted input: validate their form, cap their length, and generate a new internal value when necessary. The logger and exception adapter should read from the same context rather than accepting independently assembled ID fields at every call site.

Evaluate signal quality before changing alert policy

The notebook-to-prod move should begin with exported, redacted events and an eval, not a new alert rule. The following Python example scores a deliberately small synthetic fixture. It asks whether terminal failures are captured, whether successful retries leak into the action queue, and whether logged runs retain enough cost and latency fields for analysis. Replace the fixture with a representative, sanitized export; the code makes no claim about production rates.

from collections import defaultdict


events = [
    {
        "agent_run_id": "run-a",
        "kind": "step",
        "outcome": "retry",
        "duration_ms": 900,
        "input_tokens": 420,
        "output_tokens": 0,
        "tracked_exception": False,
    },
    {
        "agent_run_id": "run-a",
        "kind": "run",
        "outcome": "success",
        "duration_ms": 2400,
        "input_tokens": 880,
        "output_tokens": 190,
        "tracked_exception": False,
    },
    {
        "agent_run_id": "run-b",
        "kind": "run",
        "outcome": "failed",
        "duration_ms": 5100,
        "input_tokens": 1300,
        "output_tokens": 75,
        "tracked_exception": True,
    },
]


def evaluate_signal_policy(rows):
    runs = defaultdict(list)
    for row in rows:
        runs[row["agent_run_id"]].append(row)

    terminal_failures = 0
    captured_terminal_failures = 0
    noisy_retry_captures = 0
    measurable_runs = 0

    for run_events in runs.values():
        terminal = next(row for row in run_events if row["kind"] == "run")
        has_measurements = all(
            field in terminal
            for field in ("duration_ms", "input_tokens", "output_tokens")
        )
        measurable_runs += int(has_measurements)

        if terminal["outcome"] == "failed":
            terminal_failures += 1
            captured_terminal_failures += int(terminal["tracked_exception"])

        noisy_retry_captures += sum(
            row["kind"] == "step"
            and row["outcome"] == "retry"
            and row["tracked_exception"]
            for row in run_events
        )

    return {
        "terminal_capture_rate": (
            captured_terminal_failures / terminal_failures
            if terminal_failures
            else None
        ),
        "noisy_retry_captures": noisy_retry_captures,
        "measurement_coverage": measurable_runs / len(runs),
    }


print(evaluate_signal_policy(events))

Run this check against labeled eval cases in continuous integration, then compare it with production aggregates after deployment. The useful measures are terminal-failure capture coverage, duplicate exception events per run, successful retries sent to triage, correlation coverage, and measurement-field coverage. Keep latency and token distributions segmented by operation and outcome; a single average can conceal a slow retry path.

This is also where prompt-cost awareness belongs. Cost analysis needs usage fields on successful and failed attempts, while error tracking needs enough context to locate the relevant run. Shipping full prompts into both systems adds exposure and storage volume without guaranteeing better diagnosis. Prefer prompt template versions, model identifiers, token counts, tool names, and redacted hashes when those answer the operational question.

What to measure before copying this design?

First measure how often a terminal failure has a usable stack and correlation ID, how often one run creates multiple triage events, and how many successful runs contain internal retries. Then measure whether responders can move from an exception to the complete log trail with one identifier. A technically present ID that changes at a queue boundary is missing in practice.

Also test cardinality and retention decisions. User IDs, raw URLs, prompt text, and arbitrary exception messages are poor dimensions for aggregation and may carry sensitive data. Stable operation names and bounded error types are easier to reason about. Sampling can be appropriate for repetitive success logs, but retain the fields needed to estimate latency and token usage honestly, and define a separate policy for security-relevant records.

Don't copy the destination split until the eval answers two questions: does an error-tracking event reliably mean someone can act, and do the linked logs reconstruct the expensive path without exposing sensitive content? If either answer is no, adjust the event contract and retry boundary first. Tool choice comes later.

References

• https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html
• https://nodejs.org/api/async_context.html
• https://www.w3.org/TR/trace-context/
• https://opentelemetry.io/docs/specs/otel/logs/