lib.observability
OpenTelemetry-based observability primitives
@lssm-tech/lib.observabilitybun add @lssm-tech/lib.observabilityManifest declarations describe the current workspace; they do not verify registry publication or runtime execution.
Package guide
./signals owns the canonical signal and evidence declaration family. Its signal-spec, evidence-record and database-signals leaves preserve the existing schemas, canonical identifiers, validation errors and DocBlocks. Historical ContractSpec signal imports forward to these same implementations. These entries validate supplied observations; they do not emit telemetry, persist evidence, evaluate current policy or authorize actions. Emission and tenant-scoped evidence ports remain in the existing instrumentation facade.
The local no-emit typecheck uses the repository common root to check the RuntimeCore compatibility fixture alongside this package's sources. Production declaration builds select tsconfig.build.json, retaining rootDir: src and excluding tests, specs and test-only directories from emitted declarations. The source typecheck still includes these fixtures through tsconfig.json; packed-consumer qualification retains its own package boundaries.
Website: https://contractspec.io
OpenTelemetry-based observability primitives.
What It Provides
- Layer: lib.
- Consumers: evolution, progressive-delivery, bundles.
src/pipeline/contains pipeline stages and orchestration helpers.ObservabilityPortandErrorReportingPortexpose vendor-neutral OTel signal contracts. Privacy filtering removes secret, raw payload, and personal fields by default, including separator, case, and camel-case aliases; bounded dispatchers isolate exporter outages from business work.- W3C
traceparent/tracestatecarrier helpers preserve context across HTTP, queues, jobs, webhooks, MCP calls, and other synchronous or asynchronous boundaries. Incomingtraceparentvalues are exact (surrounding whitespace is rejected), whiletracestatemembers enforce W3C syntax, uniqueness, and member and total-size limits. Only ASCII space and tab are accepted as optional whitespace around member separators. - Related ContractSpec packages include
@lssm-tech/lib.contracts-integrations,@lssm-tech/lib.contracts-spec,@lssm-tech/lib.lifecycle,@lssm-tech/tool.bun,@lssm-tech/tool.typescript. src/pipeline/contains pipeline stages and orchestration helpers.
Installation
npm install @lssm-tech/lib.observability
or
bun add @lssm-tech/lib.observability
Usage
Import the root entrypoint from @lssm-tech/lib.observability, or choose a documented subpath when you only need one part of the package surface.
Architecture
src/anomalyis part of the package's public or composition surface.src/index.tsis the root public barrel and package entrypoint.src/intentis part of the package's public or composition surface.src/loggingis part of the package's public or composition surface.src/metricsis part of the package's public or composition surface.src/pipeline/contains pipeline stages and orchestration helpers.src/telemetryis part of the package's public or composition surface.OperationalImprovementAnalyticsReaderprojects an explicit PostHog/HogQL metadata allowlist into sanitized operational signals and plan-bound observation results. It never selects raw prompts, payloads, credentials, or personal fields.
Public Entry Points
- Export
.resolves through./src/index.ts. - Export
./anomaly/alert-managerresolves through./src/anomaly/alert-manager.ts. - Export
./anomaly/anomaly-detectorresolves through./src/anomaly/anomaly-detector.ts. - Export
./anomaly/baseline-calculatorresolves through./src/anomaly/baseline-calculator.ts. - Export
./anomaly/root-cause-analyzerresolves through./src/anomaly/root-cause-analyzer.ts. - Export
./intent/aggregatorresolves through./src/intent/aggregator.ts. - Export
./intent/detectorresolves through./src/intent/detector.ts. - Export
./loggingresolves through./src/logging/index.ts. It exposes the OTel-correlatedLoggerand the host structured JSON logger (createStructuredLogger,hashTenantRef):ctx, msgcalls, child bindings, injectable sink, andtenant_idemitted only as an opaquetenant_ref_hash. - Export
./metricsresolves through./src/metrics/index.ts. - Export
./pipeline/evolution-pipelineresolves through./src/pipeline/evolution-pipeline.ts. - Export
./telemetry/operational-improvement-readerresolves through./src/telemetry/operational-improvement-reader.ts. - The root entry point exports the platform ports, privacy sanitizer, resilient dispatcher, and W3C trace-context helpers.
- Keep the public subpath list aligned with
package.json.
Local Commands
bun run dev— contractspec-bun-build devbun run build— contractspec-bun-build buildbun run test— bun test --pass-with-no-testsbun run lint— bun lint:fixbun run lint:check— biome check .bun run lint:fix— biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .bun run typecheck— tsgo --noEmitbun run publish:pkg— bun publish --tolerate-republish --ignore-scripts --verbosebun run publish:pkg:canary— bun publish:pkg --tag canarybun run clean— rimraf dist .turbobun run build:bundle— contractspec-bun-build transpilebun run build:types— contractspec-bun-build typesbun run prebuild— contractspec-bun-build prebuild
Recent Updates
- Replace eslint+prettier by biomejs to optimize speed.
- Circular import issue.
- Normalize formatting across contracts-integrations, composio, and observability.
- Add AI provider ranking system with ranking-driven model selection.
Notes
- OTel span and metric naming conventions must stay consistent across the platform.
- Pipeline interfaces are adapter boundaries — do not leak vendor-specific details.
- Anomaly detection thresholds affect alerting; changes require validation.
Canonical source ownership: @lssm-tech/lib.contracts-runtime-kernel owns the existing framework-neutral implementation; module.forms/runtime owns the existing Forms service and FormsPlatformError; Observability/contracts-runtime owns the existing automatic backend event binding. Legacy five maps and default behavior are preserved. Clean artifact qualification and runtime authority remain separate requirements.
The contracts-runtime leaf owns the existing event binding. It retains the original root-selected singleton/backend initialization, logger-only override, active trace context, meter namespace, metric identities/names/tags, safe economic filtering and unsubscribe. No SDK/exporter starts. All prior public roots stay exact. Producer declarations/physical consumers/release/final-tree acceptance remain pending.
Canonical telemetry tracking, anomaly monitoring and registry implementations belong to Observability. Legacy telemetry leaves forward to the same constructors; privacy masking, sampling, defaults, provider dispatch and anomaly callback ordering are preserved. Clean declarations and physical consumers remain to be qualified.
Complete provider-neutral analytics request, reader and writer contracts are owned by Observability. Existing Integration provider leaves forward to the same full declarations. Concrete adapters and query execution remain with their existing implementations.
Portable signal schemas and evidence validation are owned by @lssm-tech/lib.observability-spec. Existing /signals/signal-spec and /signals/evidence-record leaves forward the same canonical objects. Database signal defaults remain here.
Canonical telemetry V2 schemas, validation, digests and delivery taxonomy preserve historical identities. The operations/audit leaves own portable audit queries, export/evidence commands and pipeline-health declarations with original retention, auth and signing requirements. Importing these leaves does not initialize telemetry or execute exports.
The shared/audit and shared/window leaves preserve original schema identities; operations/registry.audit retains the existing audit contract registration helper.
Relationships
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
17 declarations
@lssm-tech/lib.crypto-utilsworkspace:^
Read the package manual ↗@lssm-tech/lib.lifecycleworkspace:^
Read the package manual ↗@opentelemetry/exporter-metrics-otlp-http^0.222.0
@opentelemetry/exporter-trace-otlp-http^0.222.0
@opentelemetry/resources^2.10.0
@opentelemetry/sdk-metrics^2.11.0
Declared capabilities
OpenTelemetry-based observability primitives
Scripts
publish:pkgbun publish --tolerate-republish --ignore-scripts --verbosepublish:pkg:canarybun publish:pkg --tag canarybuildcontractspec-bun-build buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typesdevcontractspec-bun-build devcleanrimraf dist .turbolintbun lint:fixlint:fixnode ../../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../../scripts/biome.cjs check --write .lint:checknode ../../../../scripts/biome.cjs check .testbun test --pass-with-no-testsprebuildcontractspec-bun-build prebuildtypechecktsgo --noEmit --rootDir ../../../..