100 lines
10 KiB
Markdown
100 lines
10 KiB
Markdown
# @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";
|
|
```
|