RAG Pipeline Utils v2.7.1: Clearer Errors and Correct Metrics

v2.7.1 is a small patch for the observability and error helpers. createError now gives every error code its own message, metrics no longer hand back the wrong kind of metric or lose error counts, and the event logger's constants cover every event it records. Nothing in the pipeline itself changes.

npm install @devilsdev/rag-pipeline-utils@2.7.1

These were found while writing documentation for every export for the generated API reference in 2.7.0: describing each function exactly meant reading what it does, and a few did less than they promised.

Every error code has a message

createError(code, context) builds an error whose message and suggestions come from the code's template. 14 of the codes in ERROR_CODES had no template, so they fell back to the "unknown error" message, among them NETWORK_TIMEOUT, FS_READ_ERROR, DAG_EXECUTION_FAILED and AUTH_INSUFFICIENT_PERMISSIONS. Each now has its own:

import { createError, ERROR_CODES } from "@devilsdev/rag-pipeline-utils";

const error = createError(ERROR_CODES.NETWORK_TIMEOUT, {
  url: "http://localhost:6333",
});

console.log(error.message); // "Request to http://localhost:6333 timed out"
console.log(error.suggestions.length); // 2

A suggestion whose placeholder has no value in the context is now left out, instead of showing a literal Current value: {currentValue}.

Metrics

• getOrCreateCounter, getOrCreateHistogram and getOrCreateGauge returned whatever was registered under a name, even a metric of another type, so the mistake surfaced later as an unrelated error such as inc is not a function. They now throw at once:

  import { metrics } from "@devilsdev/rag-pipeline-utils";
  
  const registry = new metrics.MetricsRegistry();
  registry.getOrCreateHistogram("latency", "Query latency");
  
  try {
    registry.getOrCreateCounter("latency");
  } catch (error) {
    console.log(error.message); // 'Metric "latency" is registered as a Histogram, not a Counter'
  }

• pipelineMetrics.recordError(type, component) counted only the types plugin and stage, so an llm or network error was missing from errors.total. Every type is counted now.

• operationsActive is now a Gauge, so it goes down when an operation ends without code writing to a counter's value. It still never goes below 0.

• An empty Histogram reported min: Infinity and max: -Infinity from getStatistics(). They are null now, which is also what JSON output showed before.

Event logger constants

eventLogger.EventTypes and EventSeverity were missing three values PipelineEventLogger records: STAGE_END, MEMORY_WARNING and WARN. They are there now, so you can filter the history with constants:

import { eventLogger } from "@devilsdev/rag-pipeline-utils";

const { PipelineEventLogger, EventTypes } = eventLogger;
const events = new PipelineEventLogger();
events.logStageStart("retrieve");
events.logStageEnd("retrieve", 12);

const ended = events.getEventHistory({ eventType: EventTypes.STAGE_END });
console.log(ended.length); // 1

The recorded values themselves ("stage.end", "memory.warning", "warn") don't change.

Also checked: Ollama

2.7.0's benchmarks found that QdrantRetriever lost about 40 ms per request to compressed responses. OllamaConnector was measured against a real Ollama 0.40 server the same way: Ollama doesn't compress its responses, and the connector is as fast as plain HTTP (about 7 ms per all-minilm embedding), so it needs no change.

Upgrading

There are no breaking changes. Two things behave differently:

• A getOrCreate… call that reuses a name for another metric type now throws, rather than returning a metric that fails later.
• An empty histogram's min and max are null, so code that compared them with Infinity should check for null.

The full list of changes is in the CHANGELOG.