@devopsplaybook.io/otel-utils 1.1.0-beta.21.b48a156 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +165 -1
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1 +1,165 @@
1
- # otel-utils
1
+ # otel-utils
2
+
3
+ Utility library that simplifies OpenTelemetry integration for Node.js services. Provides standardized tracing, structured logging, and metrics export with minimal boilerplate.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @devopsplaybook.io/otel-utils
9
+ ```
10
+
11
+ ## Configuration
12
+
13
+ All classes accept a `ConfigOTelInterface` object:
14
+
15
+ | Field | Type | Default | Description |
16
+ | --------------------------------------------------------- | ---------- | ------- | ------------------------------- |
17
+ | `SERVICE_ID` | `string` | — | Service identifier (required) |
18
+ | `VERSION` | `string` | — | Service version (required) |
19
+ | `OPENTELEMETRY_COLLECTOR_HTTP_TRACES` | `string?` | — | OTLP HTTP endpoint for traces |
20
+ | `OPENTELEMETRY_COLLECTOR_HTTP_METRICS` | `string?` | — | OTLP HTTP endpoint for metrics |
21
+ | `OPENTELEMETRY_COLLECTOR_HTTP_LOGS` | `string?` | — | OTLP HTTP endpoint for logs |
22
+ | `OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS` | `number?` | `60` | Log export interval |
23
+ | `OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS` | `number?` | `60` | Metrics export interval |
24
+ | `OPENTELEMETRY_COLLECTOR_AWS` | `boolean?` | — | AWS-specific feature flag |
25
+ | `OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER` | `string?` | — | Bearer token for collector auth |
26
+
27
+ When a collector endpoint is not provided, the corresponding signal (traces, logs, or metrics) is initialized with no export — the provider is still available but no data is sent.
28
+
29
+ ## Exported Classes
30
+
31
+ ### StandardTracer
32
+
33
+ Sets up a global `NodeTracerProvider` with:
34
+
35
+ - AWS X-Ray ID generator (`AWSXRayIdGenerator`)
36
+ - OTLP HTTP trace exporter (optional, when `OPENTELEMETRY_COLLECTOR_HTTP_TRACES` is set)
37
+ - `AsyncHooksContextManager` for automatic context propagation
38
+ - Service resource attributes (name, version, hostname)
39
+
40
+ ```typescript
41
+ import { StandardTracer } from "@devopsplaybook.io/otel-utils";
42
+
43
+ const tracer = new StandardTracer(config);
44
+ const span = tracer.startSpan("my-operation");
45
+ // ... do work ...
46
+ span.end();
47
+ ```
48
+
49
+ **Methods:**
50
+
51
+ - `startSpan(name, parentSpan?)` — Creates a span. When no `parentSpan` is provided, adds `http.request_method=BACKEND` and `http.route` attributes. Span names are sanitized to `[a-zA-Z0-9-_/]`.
52
+ - `static updateHttpHeader(context, headers?)` — Injects W3C trace context into an HTTP headers object for propagation to downstream services.
53
+
54
+ ### StandardLogger
55
+
56
+ Initializes a `LoggerProvider` with an OTLP log exporter and a `BatchLogRecordProcessor` (`maxQueueSize: 2048`).
57
+
58
+ ```typescript
59
+ import { StandardLogger } from "@devopsplaybook.io/otel-utils";
60
+
61
+ const logger = new StandardLogger();
62
+ logger.initOTel(config);
63
+
64
+ const moduleLog = logger.createModuleLogger("my-module");
65
+ moduleLog.info("Hello world");
66
+ ```
67
+
68
+ **Methods:**
69
+
70
+ - `initOTel(config)` — Initializes the logger provider and optional OTLP exporter.
71
+ - `getLogger()` — Returns the underlying OTel `Logger` or `undefined`.
72
+ - `createModuleLogger(moduleName)` — Creates a `ModuleLogger` scoped to a module name.
73
+
74
+ ### ModuleLogger
75
+
76
+ Scoped logger that prefixes all output with a module name. Logs to both `console.log` and (when available) the OTel Logger.
77
+
78
+ ```typescript
79
+ const log = logger.createModuleLogger("api");
80
+ log.info("request received");
81
+ log.warn("rate limit approaching");
82
+ log.error("connection failed", new Error("timeout"));
83
+ log.info("processing complete", activeSpan); // attach trace context
84
+ ```
85
+
86
+ **Methods:**
87
+
88
+ - `info(message, context?)` — Log at INFO level.
89
+ - `warn(message, context?)` — Log at WARN level.
90
+ - `error(message, error?, context?)` — Log at ERROR level with optional `Error` and span context. Attaches `exception.type`, `exception.message`, and `exception.stacktrace` attributes.
91
+
92
+ When a `Span` is passed as `context`, the log record includes `span.id` and `trace.id` attributes for trace correlation.
93
+
94
+ ### StandardMeter
95
+
96
+ Creates a `MeterProvider` with an optional `PeriodicExportingMetricReader` (`concurrencyLimit: 5`). Provides convenience factories for common metric types.
97
+
98
+ ```typescript
99
+ import { StandardMeter } from "@devopsplaybook.io/otel-utils";
100
+
101
+ const meter = new StandardMeter(config);
102
+
103
+ const requestCount = meter.createCounter("requests.total");
104
+ requestCount.add(1);
105
+
106
+ const latency = meter.createHistogram("requests.latency");
107
+ latency.record(42);
108
+
109
+ const activeUsers = meter.createUpDownCounter("users.active");
110
+ activeUsers.add(1);
111
+
112
+ const cpuGauge = meter.createObservableGauge(
113
+ "cpu.usage",
114
+ (result) => result.observe(cpuPercent),
115
+ "Current CPU usage",
116
+ );
117
+ ```
118
+
119
+ **Methods:**
120
+
121
+ - `createCounter(key)` — Creates a `Counter` with name `${serviceName}.${key}`.
122
+ - `createUpDownCounter(key)` — Creates an `UpDownCounter`.
123
+ - `createHistogram(key)` — Creates a `Histogram`.
124
+ - `createObservableGauge(key, callback, description?)` — Creates an `ObservableGauge` with a callback. Description is optional.
125
+
126
+ ## Internal Utilities
127
+
128
+ ### createOTelResource
129
+
130
+ Shared internal utility that creates an `OTelResource` with `service.name`, `service.version`, and `network.local.address` (hostname). The hostname is cached at module load time to minimize system calls.
131
+
132
+ ```typescript
133
+ // Used internally by StandardTracer, StandardLogger, and StandardMeter
134
+ ```
135
+
136
+ ## Architecture
137
+
138
+ ```
139
+ Application
140
+ ├── StandardTracer ──► OTLP Trace Exporter ──► Collector / otel-light
141
+ ├── StandardLogger ──► OTLP Log Exporter ──► Collector / otel-light
142
+ │ └── ModuleLogger (scoped per module)
143
+ └── StandardMeter ──► OTLP Metric Exporter ──► Collector / otel-light
144
+ └── PeriodicExportingMetricReader
145
+ ```
146
+
147
+ All three signals share the same service identity (name + version) and resource attributes via `createOTelResource`. Export is optional per signal — only configured when the corresponding `OPENTELEMETRY_COLLECTOR_HTTP_*` endpoint is set.
148
+
149
+ ## Dependencies
150
+
151
+ - `@opentelemetry/api` / `@opentelemetry/api-logs` — OpenTelemetry API interfaces
152
+ - `@opentelemetry/sdk-trace-node` / `@opentelemetry/sdk-trace-base` — Tracing SDK
153
+ - `@opentelemetry/sdk-metrics` — Metrics SDK
154
+ - `@opentelemetry/sdk-logs` — Logging SDK
155
+ - `@opentelemetry/exporter-trace-otlp-http` / `@opentelemetry/exporter-metrics-otlp-http` / `@opentelemetry/exporter-logs-otlp-http` — OTLP HTTP exporters
156
+ - `@opentelemetry/id-generator-aws-xray` — AWS X-Ray trace ID format
157
+ - `@opentelemetry/context-async-hooks` — Async context management
158
+ - `@opentelemetry/core` — W3C trace context propagation
159
+ - `@opentelemetry/resources` / `@opentelemetry/semantic-conventions` — Resource attributes
160
+
161
+ ## Build
162
+
163
+ ```bash
164
+ npm run build # tsc → dist/
165
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@devopsplaybook.io/otel-utils",
3
- "version": "1.1.0-beta.21.b48a156",
3
+ "version": "1.1.0",
4
4
  "description": "Utility to simplify integration with Open Telemetry",
5
5
  "keywords": [
6
6
  "Open",