# @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.

<!-- begin:auto-docs -->
## Documentation tree

- [propagation](./src/core/propagation/propagation.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [propagation](./src/core/propagation/propagation.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [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](./src/core/sdk/sdk-factory.md) — Provides the `createSdk` factory function — the primary entry point for constructing an `OtelSdk` instance from a valid…
- [errors](./src/errors/opentelemetry-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [opentelemetry-error](./src/errors/opentelemetry-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [schemas](./src/schemas/otel-config.schema.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [otel-config.schema](./src/schemas/otel-config.schema.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [metrics-utils](./src/utils/metrics-utils.md) — Provides thin factory and recording helpers that wrap the `@opentelemetry/api` metrics API with sensible defaults and e…
- [resource](./src/utils/resource.md) — Builds a frozen OpenTelemetry resource attribute map from service identity configuration fields. Resource attributes ar…
- [span-utils](./src/utils/span-utils.md) — Provides ergonomic helper functions for working with OpenTelemetry spans. Rather than writing the same try/catch/finall…
<!-- end:auto-docs -->  - [propagation](./src/core/propagation/propagation.md) — <!-- begin:auto-docs --> _(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](./src/core/sdk/sdk-factory.md) — Provides the `createSdk` factory function — the primary entry point for constructing an `OtelSdk` instance from a valid…
- [errors](./src/errors/opentelemetry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [opentelemetry-error](./src/errors/opentelemetry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/otel-config.schema.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel-config.schema](./src/schemas/otel-config.schema.md) — <!-- begin:auto-docs --> _(no submodules)_- [metrics-utils](./src/utils/metrics-utils.md) — Provides thin factory and recording helpers that wrap the `@opentelemetry/api` metrics API with sensible defaults and e…
- [resource](./src/utils/resource.md) — Builds a frozen OpenTelemetry resource attribute map from service identity configuration fields. Resource attributes ar…
- [span-utils](./src/utils/span-utils.md) — Provides ergonomic helper functions for working with OpenTelemetry spans. Rather than writing the same try/catch/finall…
- [propagation](./src/core/propagation/propagation.md) — <!-- begin:auto-docs --> _(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](./src/core/sdk/sdk-factory.md) — Provides the `createSdk` factory function — the primary entry point for constructing an `OtelSdk` instance from a valid…
- [errors](./src/errors/opentelemetry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [opentelemetry-error](./src/errors/opentelemetry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/otel-config.schema.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel-config.schema](./src/schemas/otel-config.schema.md) — <!-- begin:auto-docs --> _(no submodules)_- [metrics-utils](./src/utils/metrics-utils.md) — Provides thin factory and recording helpers that wrap the `@opentelemetry/api` metrics API with sensible defaults and e…
- [resource](./src/utils/resource.md) — Builds a frozen OpenTelemetry resource attribute map from service identity configuration fields. Resource attributes ar…
- [span-utils](./src/utils/span-utils.md) — Provides ergonomic helper functions for working with OpenTelemetry spans. Rather than writing the same try/catch/finall…
- [propagation](./src/core/propagation/propagation.md) — <!-- begin:auto-docs --> _(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](./src/core/sdk/sdk-factory.md) — Provides the `createSdk` factory function — the primary entry point for constructing an `OtelSdk` instance from a valid…
- [errors](./src/errors/opentelemetry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [opentelemetry-error](./src/errors/opentelemetry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/otel-config.schema.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel-config.schema](./src/schemas/otel-config.schema.md) — <!-- begin:auto-docs --> _(no submodules)_- [metrics-utils](./src/utils/metrics-utils.md) — Provides thin factory and recording helpers that wrap the `@opentelemetry/api` metrics API with sensible defaults and e…
- [resource](./src/utils/resource.md) — Builds a frozen OpenTelemetry resource attribute map from service identity configuration fields. Resource attributes ar…
- [span-utils](./src/utils/span-utils.md) — Provides ergonomic helper functions for working with OpenTelemetry spans. Rather than writing the same try/catch/finall…
- [propagation](./src/core/propagation/propagation.md) — <!-- begin:auto-docs --> _(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](./src/core/sdk/sdk-factory.md) — Provides the `createSdk` factory function — the primary entry point for constructing an `OtelSdk` instance from a valid…
- [errors](./src/errors/opentelemetry-error.md) — <!-- begin:auto-docs --> _(no submodules)_  - [opentelemetry-error](./src/errors/opentelemetry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/otel-config.schema.md) — <!-- begin:auto-docs --> _(no submodules)_  - [otel-config.schema](./src/schemas/otel-config.schema.md) — <!-- begin:auto-docs --> _(no submodules)_- [metrics-utils](./src/utils/metrics-utils.md) — Provides thin factory and recording helpers that wrap the `@opentelemetry/api` metrics API with sensible defaults and e…
- [resource](./src/utils/resource.md) — Builds a frozen OpenTelemetry resource attribute map from service identity configuration fields. Resource attributes ar…
- [span-utils](./src/utils/span-utils.md) — 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](src/errors/opentelemetry-error.md) | Error class and code registry |
| `sdk` | [src/core/sdk/noop-sdk.md](src/core/sdk/noop-sdk.md) | `OtelSdk` interface and `NoopSdk` implementation |
| `sdk-factory` | [src/core/sdk/sdk-factory.md](src/core/sdk/sdk-factory.md) | `createSdk` — validated config → SDK instance |
| `span-utils` | [src/utils/span-utils.md](src/utils/span-utils.md) | `withSpan`, `recordException`, `addAttributes`, `getTraceContext` |
| `metrics-utils` | [src/utils/metrics-utils.md](src/utils/metrics-utils.md) | `createCounter`, `createHistogram`, `createGauge`, `recordDuration` |
| `resource` | [src/utils/resource.md](src/utils/resource.md) | `createResource` — OTel resource attribute builder |
| `propagation` | [src/core/propagation/propagation.md](src/core/propagation/propagation.md) | W3C traceparent inject/extract/parse/build |

## Quick Start

```ts
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

```ts
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";
```