Skip to content
reaatechREAATECH

@reaatech/agents-markdown-observability

npm v1.0.0

Provides structured Pino logging, OpenTelemetry metrics, and dashboard generation utilities for the `@reaatech/agents-markdown-*` ecosystem. It exports a collection of logging functions, a `recordOperation` wrapper for async tasks, and a `MetricsManager` singleton to track process-level telemetry.

npm →source →

@reaatech/agents-markdown-observability

npm version License: MIT CI

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Structured logging via Pino, OpenTelemetry tracing and metrics, and dashboard aggregation for the @reaatech/agents-markdown-* ecosystem.

Installation

terminal
npm install @reaatech/agents-markdown-observability
# or
pnpm add @reaatech/agents-markdown-observability

Feature Overview

  • Structured logging — Pino-based JSON logging with PII redaction, request IDs, and severity levels
  • OpenTelemetry metrics — Counters for operations, validation errors, lint warnings, files processed, and scaffold generations; histograms for operation duration
  • Timed operation wrapper — recordOperation wraps any async function with automatic duration tracking
  • Dashboard aggregation — buildDashboardSummary and renderDashboardMarkdown for at-a-glance observability
  • Singleton metrics manager — Shared MetricsManager across the process lifetime

Quick Start

typescript
import {
  info,
  error,
  recordOperation,
  buildDashboardSummary,
  renderDashboardMarkdown,
} from "@reaatech/agents-markdown-observability";
 
info("lint", "Linting AGENTS.md", { path: "./AGENTS.md" });
 
const result = await recordOperation("lint", async () => {
  // Your lint logic here — duration is automatically recorded
  return lintResult;
});
 
error("validate", "Validation failed", {
  path: "./AGENTS.md",
  errorCount: 3,
  warningCount: 2,
});

API Reference

Logging

All convenience loggers produce structured JSON logs via Pino. They accept an operation name, a message, and an optional data object.

typescript
function info(operation: string, message: string, data?: Record<string, unknown>): void
function error(operation: string, message: string, data?: Record<string, unknown>): void
function warn(operation: string, message: string, data?: Record<string, unknown>): void
function debug(operation: string, message: string, data?: Record<string, unknown>): void

log(entry)

Low-level structured log with explicit LogEntry shape. Applies PII redaction.

typescript
interface LogEntry {
  timestamp: string;
  level: "DEBUG" | "INFO" | "WARN" | "ERROR";
  service: string;
  operation: string;
  message: string;
  duration_ms?: number;
  success?: boolean;
  errors?: number;
  warnings?: number;
  request_id?: string;
}
 
function log(entry: LogEntry): void

setLogger(logger)

Replace the Pino logger instance for custom transport/level configuration.

Metrics

recordOperation(operation, fn)

Timed operation wrapper. Records operation count and duration histogram. Returns the function’s result.

typescript
type OperationType = "parse" | "validate" | "lint" | "scaffold" | "format" | "report";
 
async function recordOperation<T>(
  operation: OperationType,
  fn: () => Promise<T>
): Promise<T>

MetricsManager

Singleton accessor and class. Records counters and histograms via OpenTelemetry.

typescript
class MetricsManager {
  recordOperation(operation: OperationType, durationMs: number): void;
  recordValidationErrors(count: number): void;
  recordValidationWarnings(count: number): void;
  recordLintErrors(count: number): void;
  recordLintWarnings(count: number): void;
  recordFileProcessed(count: number): void;
  recordScaffoldGeneration(count: number): void;
  shutdown(): Promise<void>;
}
 
function getMetricsManager(): MetricsManager

METRIC_NAMES

Exported constants for all 8 metric names:

ConstantMetric
OPERATIONS_TOTALCounter: total operations by type
OPERATIONS_DURATION_MSHistogram: operation latency
VALIDATION_ERRORSCounter: validation errors found
VALIDATION_WARNINGSCounter: validation warnings found
LINTING_ERRORSCounter: lint errors found
LINTING_WARNINGSCounter: lint warnings found
FILES_PROCESSEDCounter: files processed
SCAFFOLD_GENERATIONSCounter: scaffold generations

Dashboard

typescript
interface DashboardSummary {
  totalOperations: number;
  failures: number;
  averageDurationMs: number;
  operationsByName: Record<string, number>;
  errorsByOperation: Record<string, number>;
}
FunctionDescription
buildDashboardSummary(entries: LogEntry[])Aggregate log entries into a summary
renderDashboardMarkdown(summary: DashboardSummary)Render summary as GitHub-flavored markdown

Related Packages

License

MIT

All packagesagents-md-kit overview