Skip to content
Mnemose

telemetry — Architecture

The @mnemose/telemetry package provides a consistent OpenTelemetry initialisation surface for all Mnemose services and the browser console.

Responsibilities

  • Initialise the OTEL SDK (tracing + metrics) with the correct exporter for the runtime environment
  • Provide a consoleTelemetry singleton for the browser console with WebTracerProvider, FetchInstrumentation, and DocumentLoadInstrumentation
  • Expose a initializeTelemetry({ serviceName }) helper for Node.js services that configures the OTLP gRPC exporter
  • Gracefully no-op when OTEL_EXPORTER_OTLP_ENDPOINT is unset (local dev without the collector)

Architecture

Browser (console)
  WebTracerProvider
    FetchInstrumentation   — traces all fetch() calls
    DocumentLoadInstrumentation — traces page loads
  → OTLP HTTP :4318 → OTEL Collector → Jaeger / Prometheus


Node.js services (gateway, kernel-broker, agent)
  NodeTracerProvider
    HttpInstrumentation    — traces Hono/HTTP requests
    PgInstrumentation      — traces Postgres queries
  → OTLP gRPC :4317 → OTEL Collector → Jaeger / Prometheus

Key Exports

ExportPurpose
initializeTelemetry(opts)Node.js service OTEL init (call before any instrumented code)
consoleTelemetryBrowser tracer singleton for the console app
consoleTelemetry.tracer(name)Get a named tracer for span creation

Local Dev Stack

The OTEL collector, Jaeger UI (:16686), and Prometheus (:9090) are configured in docker-compose.yml at the mnemose workspace root via otel-collector-config.yaml and prometheus.yml.