@omob/otel-kit 0.1.0 → 0.1.1

package/README.md

@@ -20,45 +20,25 @@ Those are the three signals of observability, and they answer different question
 
 Tracing is the one that connects the other two, and it is what this package is mostly for. You pick where traces, metrics and logs go; it handles the SDK, the sampling, the shutdown flush, and the boilerplate around spans — and stamps `trace_id` into your logs so the third column lines up with the second.
 
-## The words, briefly
-
-If you're new to OpenTelemetry, this is everything you need to read the rest of this page.
-
-A **trace** is the story of one request, start to finish. A **span** is one timed step inside that story. Spans nest, so a trace is a tree:
-
-```
-GET /login              240ms   ← the trace starts here
-├─ user.lookup          180ms
-│  └─ mongodb.find      175ms   ← this one you get for free
-└─ token.generate        12ms
-```
-
-Each span carries a name, a start and end time, a status (did it fail), and **attributes** — key/value labels like `user.id` or `http.method`. Every span in that tree shares one **trace ID**, which is how the tree gets reassembled at the other end.
-
-You get most spans for free. **Instrumentation** is code that wraps common libraries — HTTP, Mongo, Postgres, Redis — and opens a span whenever they're used. You never call it. `withSpan` is for the steps only you know are worth timing, like the two named above.
-
-**Sampling** is deciding what to keep. Tracing every request at scale is expensive, so `sampleRatio: 0.1` keeps a tenth. The choice is made once at the root and the whole tree follows it, so you never get half a trace.
-
-**Propagation** is how a trace survives a network hop. Your service puts the trace ID in an outgoing header; the next service reads it and continues the same trace instead of starting a new one. Both sides must agree on the header format — that's what `propagators` configures.
-
-An **exporter** is where the finished data is sent: your collector, Jaeger, Google Cloud, or the console. A **resource** is the facts about the service itself — name, version, environment — stamped on everything you send.
-
-Traces answer "what happened in this one request". **Metrics** are numbers over time ("requests per second"), and **logs** are the text lines you already write. This package can send all three; most people start with traces alone.
-
 ## Install
 
 ```bash
 npm install @omob/otel-kit @opentelemetry/api
 ```
 
-OTLP and Prometheus exporters are included. Google Cloud is the only one you install separately:
+That is everything for most setups. OTLP — protobuf, JSON and gRPC — and Prometheus are already included.
 
-```bash
-npm install @google-cloud/opentelemetry-cloud-trace-exporter \
-            @google-cloud/opentelemetry-cloud-monitoring-exporter
-```
+Extra packages are needed for Google Cloud only, and which one depends on the route you take:
+
+| If you use | Install |
+| --- | --- |
+| `ExporterType.GCP` for **traces** | `@google-cloud/opentelemetry-cloud-trace-exporter` |
+| `ExporterType.GCP` for **metrics** | `@google-cloud/opentelemetry-cloud-monitoring-exporter` |
+| Google Cloud over **OTLP** | `google-auth-library` — and neither of the above |
 
-If you pick an exporter you haven't installed, startup fails and tells you which package to install.
+They are independent: exporting traces to Google needs the trace package only. Google is deprecating both in favour of the OTLP route, which is covered under [recipes](https://github.com/omob/otel-kit/blob/main/docs/recipes.md).
+
+If you pick an exporter whose package is not installed, startup fails and names the package.
 
 ## Quick start
 
@@ -74,14 +54,38 @@ Telemetry.start({
   environment: process.env.NODE_ENV,
   enabled: process.env.NODE_ENV !== "test",
   traces: {
-    exporter: ExporterType.OTLP,
-    otlp: { url: "http://localhost:4318/v1/traces" },
+    exporter: ExporterType.CONSOLE,
     sampleRatio: Number(process.env.OTEL_TRACES_SAMPLE_RATIO ?? 1),
   },
+
+  // metrics and logs stay off until you add their block. Uncomment to turn them on —
+  // you get HTTP latency, event loop and heap metrics, and your existing pino or winston
+  // output bridged with its trace id, without writing any instrumentation yourself.
+  // metrics: { exporter: ExporterType.OTLP, otlp: { url: process.env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT } },
+  // logs: { exporter: ExporterType.OTLP, otlp: { url: process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT } },
+
   instrumentation: { ignoreIncomingPaths: ["/health"] },
 });
 ```
 
+`CONSOLE` needs no infrastructure — spans print to stdout, so you can confirm tracing works before you have anywhere to send it. Swap it for a real destination once you do:
+
+```ts
+traces: {
+  exporter: ExporterType.OTLP,
+  otlp: { url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT },
+  sampleRatio: Number(process.env.OTEL_TRACES_SAMPLE_RATIO ?? 1),
+}
+```
+
+**Nothing listens on port 4318 unless you run something there.** If you point at a collector that is not up, every export fails with `ECONNREFUSED` and you see no error at all — OpenTelemetry's internal logging is off by default. The quickest real destination is Jaeger, which ingests OTLP directly:
+
+```bash
+docker run -d --name jaeger -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one:1.62.0
+```
+
+Then set `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces` and open the UI at http://localhost:16686.
+
 Load it before your app:
 
 ```json
@@ -98,7 +102,7 @@ Keep the ratio at 1 while you are setting things up. Sampling below 1 is a produ
 instrumentation: { enable: [InstrumentationName.FASTIFY], ignoreIncomingPaths: ["/health"] }
 ```
 
-Without it, every request is one bare `GET` span with no `http.route`, so nothing groups by route. Express, Koa, Hapi, NestJS, Mongo, Postgres, Redis, Kafka and outbound HTTP need no such step — they are on by default. The wrinkle: the bundled Fastify instrumentation is deprecated upstream, which is *why* it is disabled. It works, and the alternative is covered under [Recipes](#recipes).
+Without it, every request is one bare `GET` span with no `http.route`, so nothing groups by route. Express, Koa, Hapi, NestJS, Mongo, Postgres, Redis, Kafka and outbound HTTP need no such step — they are on by default. The wrinkle: the bundled Fastify instrumentation is deprecated upstream, which is *why* it is disabled. It works, and the alternative is covered under [recipes](https://github.com/omob/otel-kit/blob/main/docs/recipes.md).
 
 ### Why `--require`
 
@@ -152,247 +156,49 @@ fastify.setErrorHandler((err, request, reply) =>
 );
 ```
 
-## Shutting down
-
-Spans sit in a batch buffer for up to five seconds, so a process that exits without flushing loses them — on every deploy, which is exactly when you want them.
-
-By default the package listens for SIGTERM and SIGINT, flushes, and then **hands the signal back**: your own handlers still run, and if there are none the process terminates with the conventional exit code (143 for SIGTERM, 130 for SIGINT). It never calls `process.exit` itself unless you ask it to with `exitOnSignal: true`.
-
-If your app already drains connections, own the order yourself — close the server first so no new spans are created, then flush:
-
-```ts
-Telemetry.start({ ..., handleShutdownSignals: false });
-
-const drain = async (code: number) => {
-  await app.close();
-  await Telemetry.shutdown();
-  process.exit(code);
-};
-
-process.on("SIGTERM", () => drain(143));
-process.on("SIGINT", () => drain(130));
-```
-
-Do not leave `handleShutdownSignals` on *and* call `Telemetry.shutdown()` from your own handler — one flush runs, both callers await it, but the ordering of your drain is no longer guaranteed.
-
-## Turning things off
-
-Every signal is optional and off by default. Omit what you don't want:
-
-```ts
-Telemetry.start({
-  serviceName: "my-service",
-  traces: { exporter: ExporterType.OTLP, otlp: { url } },
-  // no metrics block, no logs block — nothing is created for them
-});
-```
-
-To disable everything at once, set `enabled: false`. `Telemetry.start` becomes a no-op, no SDK is loaded. Use it for tests.
-
-## When configuration is rejected
-
-A telemetry mistake should not stop your service from serving traffic. If the configuration is rejected, `Telemetry.start` does **not** throw: it logs, leaves telemetry off, and lets your app boot. Pass `onStartupError` to route that into your own logger or alerting:
-
-```ts
-Telemetry.start({ ..., onStartupError: (error) => logger.error({ error }, "telemetry disabled") });
-```
-
-Pass a handler that rethrows if you would rather fail the boot.
-
-## Options
-
-Only `serviceName` is required. Everything else has a working default.
-
-**The service**
-
-| Option | Default | What it does |
-| --- | --- | --- |
-| `serviceName` | **required** | Name your service appears under. |
-| `serviceVersion` | — | Shows on every span as `service.version`. |
-| `environment` | — | Shows as `deployment.environment.name`. |
-| `enabled` | `true` | `false` turns everything off and loads no SDK. |
-| `resourceAttributes` | `{}` | Extra attributes on every span, metric and log. |
-| `resourceDetection` | `true` | Auto-detects host and process attributes. Stamps `process.command_args` — your argv — on everything, so set `false` if you pass secrets as flags. |
-
-**Traces**
-
-| Option | Default | What it does |
-| --- | --- | --- |
-| `traces.exporter` | `none` | `none` · `console` · `otlp` · `gcp` |
-| `traces.sampleRatio` | keep all | `0.1` keeps 10%. Children follow their parent's decision. |
-| `traces.sampler` | — | A sampler of your own. Takes precedence over `sampleRatio`. |
-| `traces.otlp.url` | — | Collector endpoint. Also takes `headers` and `timeoutMillis`. |
-| `traces.otlp.protocol` | `http/protobuf` | `http/protobuf` · `http/json` · `grpc` |
-| `traces.gcp.projectId` | `$GCP_PROJECT_ID` | Also takes `keyFile`; falls back to application default credentials. |
-| `traces.batch` | SDK defaults | `maxQueueSize`, `maxExportBatchSize`, `scheduledDelayMillis`, `exportTimeoutMillis`. Raise the queue if you drop spans under load. |
-| `traces.additionalProcessors` | `[]` | Extra span processors — scrub attributes, enrich spans, or dual-write to a second collector. |
-| `traces.sanitizeAttributes` | `true` | Drops `NaN` and `Infinity` attribute values, which some backends cannot represent. |
-| `spanLimits.attributeValueLengthLimit` | `4096` | Caps attribute size so one oversized request can't produce an unbounded span. |
-
-**Metrics and logs**
-
-| Option | Default | What it does |
-| --- | --- | --- |
-| `metrics.exporter` | `none` | `none` · `console` · `otlp` · `gcp` · `prometheus` |
-| `metrics.exportIntervalMillis` | `60000` | How often metrics are pushed. Prometheus ignores it — it's pull-based. |
-| `metrics.prometheus` | `127.0.0.1:9464` | `host`, `port`, `endpoint`. Binds loopback by default — the endpoint is unauthenticated, so only widen it behind a private network. |
-| `metrics.views` | `[]` | Histogram buckets and cardinality limits. |
-| `logs.exporter` | `none` | `none` · `console` · `otlp` |
-
-**Instrumentation and propagation**
-
-| Option | Default | What it does |
-| --- | --- | --- |
-| `instrumentation.disable` | `[]` | Instrumentations to switch off, e.g. `[InstrumentationName.DNS]`. |
-| `instrumentation.enable` | `[]` | Switch on one that's off by default. Beats `disable`. |
-| `instrumentation.ignoreIncomingPaths` | `[]` | No spans for these paths. Put your health check here. |
-| `instrumentation.config` | `{}` | Options for individual instrumentations, passed to OpenTelemetry unchanged. |
-| `instrumentation.additional` | `[]` | Instrumentations outside the auto set — community ones, or your own. |
-| `propagators` | `tracecontext`, `baggage` | Trace context formats to read and write. |
-
-**Lifecycle and diagnostics**
-
-| Option | Default | What it does |
-| --- | --- | --- |
-| `handleShutdownSignals` | `true` | Flush on SIGTERM/SIGINT, then hand the signal back. |
-| `exitOnSignal` | `false` | Call `process.exit(0)` after flushing instead of handing the signal back. |
-| `shutdownTimeoutMillis` | `5000` | Give up if the flush hangs, so shutdown can't stall. |
-| `onStartupError` | logs and continues | Called instead of throwing when the configuration is rejected. |
-| `diagLogLevel` | off | Turns on OpenTelemetry's own internal logging. |
-| `diagLogger` | console | Where that internal logging goes. |
-
-## Recipes
-
-**Jaeger** — Jaeger accepts OTLP directly, so there's no Jaeger exporter to install:
+## Metrics and logs
 
-```ts
-traces: { exporter: ExporterType.OTLP, otlp: { url: "http://jaeger:4318/v1/traces" } }
-```
+Both are off until you add their block. Neither needs code beyond the config.
 
-If services calling you send Jaeger's `uber-trace-id` header instead of W3C `traceparent`, accept both — otherwise their trace and yours end up unlinked:
+**Metrics** — add a `metrics` block:
 
 ```ts
-propagators: [PropagatorType.TRACE_CONTEXT, PropagatorType.BAGGAGE, PropagatorType.JAEGER]
-```
-
-All listed formats are written on outgoing calls, and an incoming call joins the upstream trace if any of them matches. `B3` and `B3_MULTI` cover Zipkin and Envoy/Istio meshes.
-
-**Per-instrumentation options** — anything documented upstream works here. `instrumentation.config` is keyed by package name and handed to OpenTelemetry unchanged:
-
-```ts
-instrumentation: {
-  enable: [InstrumentationName.FASTIFY],
-  ignoreIncomingPaths: ["/health"],
-  config: {
-    [InstrumentationName.HTTP]: {
-      ignoreOutgoingRequestHook: (options) => options.hostname === "metrics.internal",
-      headersToSpanAttributes: { server: { requestHeaders: ["x-request-id"] } },
-    },
-    [InstrumentationName.PG]: { enhancedDatabaseReporting: true },
-    [InstrumentationName.FASTIFY]: { requestHook: (span, info) => span.setAttribute("plugin", info.pluginName) },
-  },
+metrics: {
+  exporter: ExporterType.OTLP,
+  otlp: { url: process.env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT },
+  exportIntervalMillis: 60_000,
 }
 ```
 
-`disable`, `enable` and `ignoreIncomingPaths` are conveniences layered on top of the same map, and they win where they overlap — so `ignoreIncomingPaths` merges into your HTTP options rather than replacing them.
-
-**Every instrumentation in [`@opentelemetry/auto-instrumentations-node`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/auto-instrumentations-node) works here** — all 41 of them, Express, Koa, Hapi, NestJS, Restify, Postgres, MySQL, Mongo, Redis, Kafka, gRPC, AWS SDK and the rest. They are on by default, `InstrumentationName` has an entry for each, and their own options go through `instrumentation.config` untouched.
-
-Each documents its options in its own README:
+You immediately get, with no instrumentation of your own:
 
-- most live in [opentelemetry-js-contrib](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages) under `packages/instrumentation-<name>`
-- HTTP and gRPC live in [opentelemetry-js](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages) under `experimental/packages/opentelemetry-instrumentation-<name>`
-
-`InstrumentationName` values *are* the package names, so the enum entry tells you which README to open.
-
-Anything **not** in that set — a community instrumentation, or one you wrote — goes through `instrumentation.additional`, which takes instrumentation instances directly.
-
-Three defaults worth knowing, all decided upstream rather than here:
-
-- `fs` is off by default. It emits a span per file read and drowns everything else.
-- `fastify` is off by default because `@opentelemetry/instrumentation-fastify` is **deprecated** in favour of [`@fastify/otel`](https://www.npmjs.com/package/@fastify/otel), maintained by the Fastify team. `enable: [InstrumentationName.FASTIFY]` still works and still produces route spans, but it is unmaintained; `@fastify/otel` registers as a Fastify plugin and reports through the same global API this package sets up.
-- database instrumentations replace query values with `?`. `enhancedDatabaseReporting: true` puts the real parameters in your spans — think about customer data before turning it on.
-
-**A gRPC collector** — OTLP defaults to HTTP/protobuf on port 4318. For a collector speaking gRPC on 4317:
-
-```ts
-traces: { exporter: ExporterType.OTLP, otlp: { protocol: OtlpProtocol.GRPC, url: "http://collector:4317" } }
-```
-
-Note the HTTP protocols need the full signal path (`/v1/traces`); gRPC takes the base URL. A missing path is a silent 404 on every export.
-
-**Scrubbing attributes before they leave** — add your own span processor:
-
-```ts
-traces: { exporter: ExporterType.OTLP, additionalProcessors: [new RedactingSpanProcessor()] }
-```
+- `http.server.duration` and `http.client.duration` — request latency in and out, by route and status
+- `nodejs.eventloop.delay.p50` / `p90` / `p99`, `nodejs.eventloop.utilization` — the event loop, which is what saturates first on a busy Node service
+- `v8js.memory.heap.*` — heap usage and limit
 
-**Prometheus** — serves a scrape endpoint instead of pushing:
+For a pull-based setup, swap the exporter and Prometheus scrapes you instead:
 
 ```ts
 metrics: { exporter: ExporterType.PROMETHEUS, prometheus: { port: 9464 } }
 ```
 
-Then scrape `http://your-service:9464/metrics`.
-
-**Google Cloud**:
-
-```ts
-traces: { exporter: ExporterType.GCP, gcp: { projectId: "my-project" } }
-```
-
-Uses `GOOGLE_APPLICATION_CREDENTIALS` if it points at a readable file, otherwise application default credentials.
-
-**Seeing spans locally** — no collector needed:
+**Logs** — add a `logs` block:
 
 ```ts
-traces: { exporter: ExporterType.CONSOLE, sampleRatio: 1 }
+logs: { exporter: ExporterType.OTLP, otlp: { url: process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT } }
 ```
 
-Spans print on shutdown, since they're batched.
-
-**Quieter traces** — the noisiest instrumentations are usually DNS and net, especially with a database driver reconnecting:
-
-```ts
-instrumentation: { disable: [InstrumentationName.DNS, InstrumentationName.NET] }
-```
-
-## Troubleshooting
-
-A rejected configuration produces a `TelemetryConfigError`. It is **reported, not thrown** — telemetry switches itself off and your service still boots. `onStartupError` decides where that goes; by default it is logged.
+You do not change how you log. If you use pino, winston or bunyan, the log instrumentation bridges what you already write into OpenTelemetry, carrying the `trace_id` that ties each line to its span — so a trace links straight to the logs from that request.
 
-| Error code | Cause |
-| --- | --- |
-| `MISSING_SERVICE_NAME` | `serviceName` empty or missing. |
-| `INVALID_SAMPLE_RATIO` | `sampleRatio` outside 0–1. |
-| `UNSUPPORTED_EXPORTER` | Exporter can't handle that signal, e.g. `prometheus` for traces. |
-| `UNSUPPORTED_PROPAGATOR` | Unknown propagator name. |
-| `MISSING_OPTIONAL_DEPENDENCY` | Exporter selected but its package isn't installed. |
-
-**No traces showing up? Read the `trace_flags` on your own log lines first.** If you use pino, bunyan or winston, the log instrumentation stamps every line with the active trace:
-
-```json
-{"trace_id":"9d497527a7ec14c5a81325251113283d","span_id":"b58894198a10765d","trace_flags":"00"}
-```
-
-That one field splits the problem in half:
-
-- **`trace_flags: "00"`** — the span was created and then dropped by the sampler. Nothing was ever sent, so the collector is irrelevant. Raise `sampleRatio` to 1, or check whether an inbound `traceparent` arrived already marked unsampled — parent-based sampling honours the caller's decision.
-- **`trace_flags: "01"`** — the span was sampled and handed to the exporter, so the problem is downstream: the endpoint, the path, or the network.
-- **no `trace_id` at all** — the SDK never started, or it started after your app loaded. Check the `--require` flag.
-
-Then turn on OpenTelemetry's own logging — it is off by default, which is why a bad endpoint or an unreachable collector produces silence rather than an error:
-
-```ts
-import { DiagLogLevel } from "@opentelemetry/api";
-
-Telemetry.start({ ..., diagLogLevel: DiagLogLevel.ERROR });
-```
+Two things to weigh before turning logs on. Your log volume goes to two places, so you pay to store it twice unless you drop stdout collection. And any gap in your redaction now reaches a second system: check what your logger emits — response bodies and auth headers are the usual leaks — before pointing it at a backend.
 
-Pass `diagLogger` to send it to your own logger instead of the console. With that on, most causes announce themselves. Without it, check in order: is `enabled` true; is `traces.exporter` something other than `none`; is the path in `ignoreIncomingPaths`; is `sampleRatio` dropping them; is the collector URL reachable from inside the container.
+## More
 
-**Jaeger returns a 500 with `json: unsupported value: NaN`?** A span carried a `NaN` numeric attribute, and Go's JSON encoder cannot represent one — so Jaeger fails the whole trace, not just that attribute. Some instrumentations produce it by parsing a port or a header that was not there. The package drops non-finite attribute values before export, so this should not reach you; if you have set `sanitizeAttributes: false`, that is why.
+- [Configuration](https://github.com/omob/otel-kit/blob/main/docs/configuration.md) — every option, shutdown behaviour, and what happens when a config is rejected
+- [Recipes](https://github.com/omob/otel-kit/blob/main/docs/recipes.md) — Jaeger, Google Cloud, Prometheus, gRPC collectors, per-instrumentation options
+- [Troubleshooting](https://github.com/omob/otel-kit/blob/main/docs/troubleshooting.md) — no traces appearing, wrong service name, broken propagation
+- [Concepts](https://github.com/omob/otel-kit/blob/main/docs/concepts.md) — traces, spans, sampling and propagation, if OpenTelemetry is new to you
 
-**Everything arrives under the wrong service name?** `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES` are read by the SDK's own resource detectors, and detected attributes win over the ones you pass in code. A service mesh or a shared Helm chart injecting either will silently rename your service. Set `resourceDetection: false` to stop that.
+## Licence
 
-**Traces stop at your service** — a caller's trace doesn't continue into yours: they're probably using a propagation format you haven't listed in `propagators`.
+MIT

package/dist/telemetry.types.d.ts

@@ -8,6 +8,7 @@ import { InstrumentationName } from "./enums/instrumentation-name.enum";
 import { OtlpProtocol } from "./enums/otlp-protocol.enum";
 import { PropagatorType } from "./enums/propagator-type.enum";
 export type ResourceAttributeValue = string | number | boolean;
+export type OtlpHeaders = Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
 export type SpanHandler<T> = (span: import("@opentelemetry/api").Span) => Promise<T> | T;
 export interface IGcpTraceModule {
     TraceExporter: new (options: object) => SpanExporter;
@@ -21,7 +22,7 @@ export interface IPrometheusModule {
 export interface IOtlpOptions {
     protocol?: OtlpProtocol;
     url?: string;
-    headers?: Record<string, string>;
+    headers?: OtlpHeaders;
     timeoutMillis?: number;
 }
 export interface IGcpOptions {

package/dist/utils/otlp-options.d.ts

@@ -1,6 +1,6 @@
 import { IOtlpOptions } from "../telemetry.types";
 export declare function toOtlpExporterOptions(options?: IOtlpOptions): {
     timeoutMillis?: number | undefined;
-    headers?: Record<string, string> | undefined;
+    headers?: import("../telemetry.types").OtlpHeaders | undefined;
     url?: string | undefined;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omob/otel-kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Configurable OpenTelemetry bootstrap for Node services: traces, metrics and logs with pluggable exporters",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,7 +22,8 @@
     "lint": "eslint src test",
     "lint:fix": "eslint src test --fix",
     "test": "jest --runInBand",
-    "verify:consumers": "node scripts/verify-consumers.mjs"
+    "verify:consumers": "node scripts/verify-consumers.mjs",
+    "verify:docs": "node scripts/verify-docs.mjs"
   },
   "keywords": [
     "opentelemetry",