skills/plugins/document-navigator/docs/observability/monitor/opentelemetry/README.md

@suaveplan/opentelemetry - OpenTelemetry SDK setup and configuration helpers: tracer/meter/logger providers, resource detection, exporter configuration, and sampling strategies

Summary

OpenTelemetry SDK setup and configuration helpers for Suaveplan. Provides batteries-included OTel initialization helpers, resource detection, ergonomic span/metrics wrappers, W3C trace-context propagation utilities, and a no-op SDK façade that works without any heavyweight @opentelemetry/sdk-* packages.

Documentation tree

• propagation — (no submodules)
  • propagation — (no submodules)
• noop-sdk — Provides NoopSdk, a zero-dependency implementation of the OtelSdk interface that delegates all tracer and meter loo…
• sdk-factory — Provides the createSdk factory function — the primary entry point for constructing an OtelSdk instance from a valid…
• errors — (no submodules)
  • opentelemetry-error — (no submodules)
• schemas — (no submodules)
  • otel-config.schema — (no submodules)
• metrics-utils — Provides thin factory and recording helpers that wrap the @opentelemetry/api metrics API with sensible defaults and e…
• resource — Builds a frozen OpenTelemetry resource attribute map from service identity configuration fields. Resource attributes ar…
• span-utils — Provides ergonomic helper functions for working with OpenTelemetry spans. Rather than writing the same try/catch/finall…

- [propagation](./src/core/propagation/propagation.md) — _(no submodules)_- [noop-sdk](./src/core/sdk/noop-sdk.md) — Provides `NoopSdk`, a zero-dependency implementation of the `OtelSdk` interface that delegates all tracer and meter loo…

• sdk-factory — Provides the createSdk factory function — the primary entry point for constructing an OtelSdk instance from a valid…
• errors — (no submodules)- opentelemetry-error — (no submodules)- schemas — (no submodules)- otel-config.schema — (no submodules)- metrics-utils — Provides thin factory and recording helpers that wrap the @opentelemetry/api metrics API with sensible defaults and e…
• resource — Builds a frozen OpenTelemetry resource attribute map from service identity configuration fields. Resource attributes ar…
• span-utils — Provides ergonomic helper functions for working with OpenTelemetry spans. Rather than writing the same try/catch/finall…
• propagation — (no submodules)- noop-sdk — Provides NoopSdk, a zero-dependency implementation of the OtelSdk interface that delegates all tracer and meter loo…
• sdk-factory — Provides the createSdk factory function — the primary entry point for constructing an OtelSdk instance from a valid…
• errors — (no submodules)- opentelemetry-error — (no submodules)- schemas — (no submodules)- otel-config.schema — (no submodules)- metrics-utils — Provides thin factory and recording helpers that wrap the @opentelemetry/api metrics API with sensible defaults and e…
• resource — Builds a frozen OpenTelemetry resource attribute map from service identity configuration fields. Resource attributes ar…
• span-utils — Provides ergonomic helper functions for working with OpenTelemetry spans. Rather than writing the same try/catch/finall…
• propagation — (no submodules)- noop-sdk — Provides NoopSdk, a zero-dependency implementation of the OtelSdk interface that delegates all tracer and meter loo…
• sdk-factory — Provides the createSdk factory function — the primary entry point for constructing an OtelSdk instance from a valid…
• errors — (no submodules)- opentelemetry-error — (no submodules)- schemas — (no submodules)- otel-config.schema — (no submodules)- metrics-utils — Provides thin factory and recording helpers that wrap the @opentelemetry/api metrics API with sensible defaults and e…
• resource — Builds a frozen OpenTelemetry resource attribute map from service identity configuration fields. Resource attributes ar…
• span-utils — Provides ergonomic helper functions for working with OpenTelemetry spans. Rather than writing the same try/catch/finall…
• propagation — (no submodules)- noop-sdk — Provides NoopSdk, a zero-dependency implementation of the OtelSdk interface that delegates all tracer and meter loo…
• sdk-factory — Provides the createSdk factory function — the primary entry point for constructing an OtelSdk instance from a valid…
• errors — (no submodules) - opentelemetry-error — (no submodules)- schemas — (no submodules) - otel-config.schema — (no submodules)- metrics-utils — Provides thin factory and recording helpers that wrap the @opentelemetry/api metrics API with sensible defaults and e…
• resource — Builds a frozen OpenTelemetry resource attribute map from service identity configuration fields. Resource attributes ar…
• span-utils — Provides ergonomic helper functions for working with OpenTelemetry spans. Rather than writing the same try/catch/finall…

Packages

Module	Path	Description
errors	src/errors/opentelemetry-error.md	Error class and code registry
sdk	src/core/sdk/noop-sdk.md	OtelSdk interface and NoopSdk implementation
sdk-factory	src/core/sdk/sdk-factory.md	createSdk — validated config → SDK instance
span-utils	src/utils/span-utils.md	withSpan, recordException, addAttributes, getTraceContext
metrics-utils	src/utils/metrics-utils.md	createCounter, createHistogram, createGauge, recordDuration
resource	src/utils/resource.md	createResource — OTel resource attribute builder
propagation	src/core/propagation/propagation.md	W3C traceparent inject/extract/parse/build

Quick Start

import { createSdk } from "@suaveplan/opentelemetry/sdk";
import { withSpan } from "@suaveplan/opentelemetry/span-utils";
import { createCounter, recordDuration } from "@suaveplan/opentelemetry/metrics-utils";

const sdk = createSdk({
  serviceName: "my-service",
  serviceVersion: "1.0.0",
  environment: "production",
});

await sdk.start();

const tracer = sdk.getTracer("my-service");
const meter = sdk.getMeter("my-service");

const requestCounter = createCounter(meter, "http.request.total", "Total HTTP requests");
const latency = createHistogram(meter, "http.request.duration", "Request latency", "ms");

async function handleRequest(req: Request) {
  return withSpan(tracer, "http.handle", async (span) => {
    span.setAttribute("http.method", req.method);
    const start = Date.now();
    const response = await processRequest(req);
    requestCounter.add(1, { "http.status": response.status });
    recordDuration(latency, start, { "http.route": "/api" });
    return response;
  });
}

// Graceful shutdown
process.on("SIGTERM", () => sdk.shutdown());

Subpath Exports

import { ... } from "@suaveplan/opentelemetry";              // all exports
import { createSdk, NoopSdk } from "@suaveplan/opentelemetry/sdk";
import { withSpan, recordException } from "@suaveplan/opentelemetry/span-utils";
import { createCounter, createHistogram } from "@suaveplan/opentelemetry/metrics-utils";
import { injectTraceContext, parseTraceParent } from "@suaveplan/opentelemetry/propagation";
import { OpenTelemetryError, OTEL_CODES } from "@suaveplan/opentelemetry/errors";