@gtcx/observability

OpenTelemetry adapter for the GTCX Protocol layer. Provides injectable metrics and tracing interfaces that degrade gracefully to no-ops when OTel is not installed.

Overview

This package is a thin adapter over @opentelemetry/api. When OTel is available it routes metrics and spans to your configured collector. When OTel is not installed, all operations are no-ops — no errors, no crashes.

Protocol packages depend on IMetricsCollector from @gtcx/domain, not on this package directly. Wire this adapter at the application layer.

Exports

| Export | Description | | -------------------------------------- | -------------------------------------------------------------------------------- | | createOtelMetricsCollector(options?) | Returns an IMetricsCollector backed by OTel, or a no-op if OTel is unavailable | | withSpan(name, fn, options?) | Wraps an async function in an OTel span | | isOtelAvailable() | Returns true if @opentelemetry/api is resolvable at runtime |

Usage

import { createOtelMetricsCollector } from '@gtcx/observability';
import { createAuthMiddleware } from '@gtcx/auth';

const metrics = createOtelMetricsCollector({ meterName: 'gtcx' });

const authMiddleware = createAuthMiddleware({
  ...config,
  metrics,
});

Peer Dependencies

@opentelemetry/api is an optional peer dependency. Install it to enable real telemetry:

pnpm add @opentelemetry/api

Without it, the package operates in no-op mode — suitable for development and test environments.

Metrics Reference

See SOP/2-docs/4-operations/runbooks/monitoring.md for the full list of protocol metrics, alerting thresholds, and wiring examples.

Reference

• Monitoring Runbook
• @gtcx/domain — IMetricsCollector interface definition