Node.js 如何匯出搜尋分析以追蹤零結果查詢

The page says the internal clinical knowledge bot's zero-hit ratio has crossed its limit. On-call sees a tenant-safe dashboard built from a Node.js search analytics export, which can track the affected queries without putting raw patient text into a generic log index. It also shows the document corpus, query class, deployment marker, and a link to governed, redacted samples; critically, its count does not confuse an empty lexical result with an answer rejected later by policy.

Short answer: have the Node.js search path emit one structured event after retrieval, with an explicit outcome, corpus revision, retrieval mode, latency, and privacy-safe query fingerprint; send those events to a bounded analytics sink; aggregate both a ratio and an absolute count; and page only when the burn is sustained over two windows. A raw results.length === 0 counter is useful for debugging, but it is too ambiguous for an SLO and too easy to turn into a privacy incident.

The distinction matters in a healthtech knowledge base. “No indexed passage matched this medication query” requires content or retrieval work. “A passage matched, but authorization removed it” may be correct behavior. “Retrieval timed out” is an availability failure. One number cannot own all three responses.

How should Node.js export search analytics to track empty queries?

The earlier signal is usually not the page. It is a change in the distribution of typed outcomes, correlated with corpus revision and deploy markers: no_match rises for one corpus after an ingestion run, filtered rises after a policy change, or error rises across every corpus after a dependency slows down. The RAG architecture described by Lewis et al. separates retrieval from generation; the operational consequence is that retrieval needs its own observable result rather than a vague end-to-end “bot failed” label.

Start with a small outcome vocabulary. matched means at least one eligible chunk cleared the configured retrieval rule. no_match means retrieval completed normally but none did. filtered means candidates existed but none remained after access and policy checks. error means the attempt did not produce a valid retrieval decision. Keep abandonment separate because a canceled request says little about corpus quality.

This taxonomy prevents a nasty diagnostic mistake: lowering a similarity threshold to cure an authorization filter. That may improve the headline zero-hit graph while degrading relevance, and it does nothing for the user who was correctly denied access.

For each completed attempt, record fields with bounded cardinality:

• event schema version and event time;
• pseudonymous tenant and corpus identifiers;
• corpus revision or ingestion generation;
• retrieval mode, outcome, result count, and latency bucket;
• application release and policy revision;
• normalized-query hash plus a separately governed, redacted sample reference.

Do not put query text, document text, user identity, a stack trace, or arbitrary error strings into metric labels. OpenTelemetry's metrics data model describes attributes as dimensions, and Prometheus warns that every unique label combination creates a new time series. Query hashes are therefore event fields for controlled analysis, not metric labels. The hash also is not anonymization: a small dictionary of likely clinical questions can be hashed again. Treat it as sensitive, apply retention and access controls, and use a keyed construction if stable grouping is required.

Instrument the decision, not the HTTP response

The instrumentation point belongs after eligibility filtering and before generation. At that boundary the service knows whether retrieval itself succeeded, why it returned nothing, which corpus revision it queried, and how long the operation took. An HTTP 200 can still contain an abstention; an HTTP 500 can occur after retrieval found excellent evidence. Status codes answer a different question.

The Node.js application can publish newline-delimited JSON or the same logical record through an internal telemetry transport. The following Go program is a deliberately small analytics receiver for that contract. It validates the closed outcome set, rejects malformed records, keeps raw query text out of the schema, and exports aggregate rows that a batch job or metrics bridge can consume. The channel is bounded so analytics cannot grow memory without limit; under pressure, the handler returns 503, which lets the caller's non-blocking telemetry client apply its documented drop or retry policy without delaying the search response.

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "errors"
    "log"
    "net/http"
    "strings"
    "sync"
    "time"
)

type SearchEvent struct {
    SchemaVersion int       `json:"schema_version"`
    OccurredAt    time.Time `json:"occurred_at"`
    TenantID      string    `json:"tenant_id"`
    CorpusID      string    `json:"corpus_id"`
    CorpusRev     string    `json:"corpus_revision"`
    Mode          string    `json:"retrieval_mode"`
    Outcome       string    `json:"outcome"`
    ResultCount   int       `json:"result_count"`
    LatencyMS     int64     `json:"latency_ms"`
    QueryHash     string    `json:"query_hash"`
}

type Key struct {
    TenantID, CorpusID, CorpusRev, Mode, Outcome string
}

type Aggregate struct {
    Count        uint64 `json:"count"`
    LatencyMSSum int64  `json:"latency_ms_sum"`
}

type Store struct {
    mu   sync.Mutex
    rows map[Key]Aggregate
}

func fingerprint(key []byte, normalizedQuery string) string {
    mac := hmac.New(sha256.New, key)
    mac.Write([]byte(normalizedQuery))
    return hex.EncodeToString(mac.Sum(nil))
}

func validate(e SearchEvent) error {
    valid := map[string]bool{
        "matched": true, "no_match": true, "filtered": true, "error": true,
    }
    if e.SchemaVersion != 1 || e.OccurredAt.IsZero() {
        return errors.New("unsupported schema or missing event time")
    }
    if e.TenantID == "" || e.CorpusID == "" || e.CorpusRev == "" || !valid[e.Outcome] {
        return errors.New("missing dimension or invalid outcome")
    }
    if e.ResultCount < 0 || e.LatencyMS < 0 {
        return errors.New("negative measurement")
    }
    return nil
}

func (s *Store) add(e SearchEvent) {
    k := Key{e.TenantID, e.CorpusID, e.CorpusRev, e.Mode, e.Outcome}
    s.mu.Lock()
    a := s.rows[k]
    a.Count++
    a.LatencyMSSum += e.LatencyMS
    s.rows[k] = a
    s.mu.Unlock()
}

func main() {
    events := make(chan SearchEvent, 4096)
    store := &Store{rows: make(map[Key]Aggregate)}
    go func() {
        for e := range events {
            store.add(e)
        }
    }()

    http.HandleFunc("/events/search", func(w http.ResponseWriter, r *http.Request) {
        defer r.Body.Close()
        var e SearchEvent
        dec := json.NewDecoder(http.MaxBytesReader(w, r.Body, 32<<10))
        dec.DisallowUnknownFields()
        if err := dec.Decode(&e); err != nil || validate(e) != nil {
            http.Error(w, "invalid event", http.StatusBadRequest)
            return
        }
        select {
        case events <- e:
            w.WriteHeader(http.StatusAccepted)
        default:
            http.Error(w, "analytics queue full", http.StatusServiceUnavailable)
        }
    })

    _ = fingerprint
    log.Fatal(http.ListenAndServe(":8080", nil))
}

The unused fingerprint function is intentional in this compact example: normalization must happen in the search application, where language, casing, whitespace, and clinically meaningful punctuation are understood. Hashing before normalization splits equivalent queries. Aggressive normalization can merge different drug strengths. That choice belongs to retrieval evaluation, not to a generic receiver.

Production hardening still matters. Authenticate the producer, encrypt transport, rotate the HMAC key under a documented policy, cap request bodies, reject unknown schema versions, and measure accepted, rejected, dropped, and queued events. The event pipeline must not sit on the availability path of the bot. At-least-once delivery also requires an event ID and deduplication if exact counts matter; otherwise document that retries can inflate totals.

Turn exported events into a retrieval SLO

A useful dashboard pairs the zero-hit ratio with traffic and latency. For a window, calculate no_match / (matched + no_match) only from completed, policy-eligible retrieval decisions. Plot filtered and error separately. Always show the denominator: one miss in one query is 100%, but it is not the same operational event as 10,000 misses in 10,000 attempts.

Do not copy a universal threshold from another system. Establish a reviewed baseline per corpus and query class, then choose a service level objective from the clinical workflow's risk and the team's response capacity. A formulary corpus with constrained vocabulary may have a very different expected miss rate from free-form policy search. Retrieval quality and latency also pull against each other: broader candidate generation or reranking may reduce misses while consuming the response budget. Measure both before changing either.

An illustrative alert policy might require a minimum of 200 eligible queries, a zero-hit ratio above the corpus baseline by 5 percentage points for 15 minutes, and confirmation over a one-hour window. Those numbers are examples, not industry facts. Replay evaluation data and incident-free production history should determine the real values. Multi-window alerting follows the same capacity-planning logic used for error-budget burn alerts: one window detects a sharp regression, while the longer window filters brief noise.

Keep a small offline evaluation set alongside production telemetry. Label whether a query should retrieve evidence, which documents are relevant, and whether abstention is correct. Precision and recall are standard information-retrieval measures, while production zero-hit rate is only a proxy; a system can return a result for every query and still retrieve irrelevant evidence. This is why “make the graph green” is not an acceptance criterion.

Which response does the signal justify?

The page should carry enough dimensions to select an action without exposing content. A jump isolated to one corpus revision points toward ingestion validation: compare expected and indexed document counts, inspect parser rejection totals, and roll forward or back according to the corpus deployment policy. A rise in no_match for every revision after an application release points toward query processing or retrieval configuration. A filtered change belongs with authorization owners. An error change belongs in the availability path.

This is also where buy versus build becomes concrete. The decision is not a feature-count contest; it is an ownership decision.

Whichever path wins, preserve the event contract and an export route. A dashboard that cannot yield the underlying aggregate rows is hard to audit and hard to use in regression testing.

This design has limitations. A custom receiver is a poor fit for a team that cannot own its queue, schema migrations, retention controls, and after-hours failures; a managed telemetry service or an existing internal observability pipeline is the more defensible choice there, provided its privacy boundary and export behavior pass review. Conversely, a managed path may be unsuitable when regulated query-derived data cannot cross the organization's controlled boundary. The trade-off is operational ownership against governance and portability, not a claim that either category retrieves better evidence.

The false-positive bill arrives on call

Close the loop after every page. Record whether the alert identified a retrieval-quality regression, an expected content shift, sparse traffic, or an instrumentation defect. Then adjust the threshold through review and replay, not during an anxious incident. This feedback is part of the system.

An oversensitive zero-hit alert spends attention, encourages risky threshold changes, and teaches responders to ignore the page. An insensitive one lets a broken ingestion generation sit behind polite abstentions. The right threshold is the one that detects actionable loss of retrieval quality within the response objective while producing a page volume the owning team can actually investigate. Capacity includes humans.

Further reading

References:

• Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks: https://arxiv.org/abs/2005.11401
• OpenTelemetry metrics data model: https://opentelemetry.io/docs/specs/otel/metrics/data-model/
• Prometheus guidance on metric and label naming: https://prometheus.io/docs/practices/naming/
• Prometheus guidance on alerting: https://prometheus.io/docs/practices/alerting/
• NIST guidance on protecting personally identifiable information: https://csrc.nist.gov/pubs/sp/800/122/final
• Go crypto/hmac package: https://pkg.go.dev/crypto/hmac