Monitoring

Stack Overview

All HanseNexus apps are monitored using SigNoz with OpenTelemetry for traces, metrics, and logs.

Component	Role
SigNoz	Observability platform (traces, metrics, logs, dashboards)
OpenTelemetry Collector	DaemonSet on k3s, collects and forwards telemetry
OTel Operator	Auto-instruments Node.js pods via annotation
@hn-monorepo/monitoring	Shared package for client-side error capture

Kubernetes Instrumentation

Auto-Instrumentation

The OpenTelemetry Operator runs on the k3s cluster and auto-instruments pods that carry the annotation:

instrumentation.opentelemetry.io/inject-nodejs: "true"

This annotation is included in app Deployment manifests in k8s/apps/<app>/deployment.yaml. The operator injects the OTel Node.js agent as an init container, which automatically captures:

• HTTP request traces
• Database queries
• External API calls
• Runtime metrics

OpenTelemetry Collector

The OTel Collector runs as a DaemonSet (defined in k8s/base/signoz/) and:

• Receives telemetry from instrumented pods
• Processes and batches spans and metrics
• Exports data to the SigNoz backend in the signoz namespace

Client-Side Error Capture

The @hn-monorepo/monitoring package provides client-side error tracking via dedicated API endpoints.

How It Works

Each app exposes a /api/otel/error endpoint that receives client-side errors and forwards them to the OTel Collector. This captures:

• Unhandled JavaScript errors
• Promise rejections
• React error boundary catches
• Custom error reports

Integration

Apps import the monitoring package and initialize it in the client-side layout:

import { initMonitoring } from "@hn-monorepo/monitoring";

The package automatically hooks into window.onerror and window.onunhandledrejection to capture errors without manual instrumentation.

Local Development

For local development, OpenTelemetry can send traces to a local or remote SigNoz instance. The following environment variables are set in each app’s .env.op file:

Variable	Purpose
OTEL_EXPORTER_OTLP_ENDPOINT	URL of the OTel Collector (e.g., http://signoz-otel-collector:4317)
OTEL_SERVICE_NAME	Identifies the app in SigNoz (e.g., lexilink, calnexus)

These are resolved at runtime via op run along with other environment variables.

SigNoz Dashboard

SigNoz provides dashboards for:

• Traces: Distributed tracing across services, including latency percentiles and error rates
• Metrics: Runtime metrics (CPU, memory, event loop lag)
• Logs: Aggregated application logs with search and filtering
• Alerts: Configurable alerting rules (not currently set up)

Access the SigNoz dashboard via the signoz namespace Ingress on the k3s cluster.

Monitoring Package

The @hn-monorepo/monitoring package (packages/monitoring/) provides:

• Server-side OTel initialization helpers
• Client-side error capture and forwarding
• Shared configuration for service naming and endpoint resolution
• Type-safe error reporting utilities

Import paths follow the standard monorepo pattern:

import { ... } from "@hn-monorepo/monitoring";