@sebspark/otel 0.1.0 → 0.2.0

package/README.md

@@ -1,10 +1,12 @@
 # `@sebspark/otel`
 
-Open Telemetry implementation of logging, tracing and metrics
+Unified **OpenTelemetry** implementation for logging, tracing, and metrics — with environment detection, auto‑instrumentation, and clean console output for local development.
 
-## Usage
+---
+
+## Use logger, tracer, and metrics
 
-Run: 
+Install:
 
 ```sh
 npm install @sebspark/otel
@@ -14,145 +16,206 @@ yarn add @sebspark/otel
 pnpm add @sebspark/otel
 ```
 
-**Initialization and Context Detection**
-
-The **OpenTelemetry SDK** is automatically initialized when you import `@sebspark/otel`.
+### Initialization
 
-**This should be the first import in your application.**
+**This must be the first import in your application:**
 
 ```ts
 import '@sebspark/otel'
 ```
 
-This setup:
+Automatically:
 
-- Uses **OpenTelemetry auto-instrumentations** to trace supported libraries
-  - **HTTP**, **gRPC**, **Redis**, **PostgreSQL** etc.
-- **Auto-detects environment metadata**, including:
-  - **GCP** service name (e.g., **Cloud Run**, **GKE**, **GCE**, etc.)
-  - Instance and zone/region
-- Enables **W3C Trace Context** propagation across async operations and network boundaries
-- Automatically links logs with `trace_id` and `span_id` inside active spans
-- Supports clean shutdown via `SIGTERM` (e.g. **Cloud Run**, **Kubernetes**)
+- Initializes the OpenTelemetry SDK  
+- Auto‑instruments common libraries like **HTTP**, **gRPC**, **Redis**, **PostgreSQL**  
+- Enables W3C Trace Context propagation  
+- Detects environment and adds `resourceAttributes`  
+- Links logs with `trace_id` and `span_id`  
+- Handles graceful shutdown on `SIGTERM`
+
+---
 
-In **GCP** environments, this ensures that traces are correlated across **Cloud Logging**, **Cloud Trace**, and **Cloud Monitoring** without extra setup.
+### Logging
 
-#### Environment-aware attributes
+```ts
+import { getLogger } from '@sebspark/otel'
 
-The following values are detected and attached as `resourceAttributes`:
+const logger = getLogger()
 
-**Env Variable**        | **Attribute Key**       | **Description**
-------------------------|-------------------------|-------------------------------
-OTEL_SERVICE_NAME       | service.name            | Overrides service name
-OTEL_SERVICE_VERSION    | service.version         | Version of the current service
-K_SERVICE               | cloud.run.service       | Cloud Run service name
-K_REVISION              | cloud.run.revision      | Cloud Run revision
-K_CONFIGURATION         | cloud.run.configuration | Cloud Run config
-POD_NAME                | k8s.pod_name            | Kubernetes pod name
-POD_NAMESPACE           | k8s.namespace_name      | Kubernetes namespace
-KUBERNETES_SERVICE_HOST | cloud.orchestrator      | Set to 'kubernetes' if present
-GCP_PROJECT             | cloud.account.id        | GCP project ID
-CLOUD_PROVIDER          | cloud.provider          | e.g. 'gcp', 'aws', etc.
+logger.debug('debug message')
+logger.info('something happened')
+logger.warn('almost bad')
+logger.error('very bad')
+```
+
+Logs inside active spans automatically include:
+- `trace_id`
+- `span_id`
+- `service.name`
+- `service.version`
 
 ---
 
-### Logging
+### Tracing
 
-The logger automatically includes `trace_id` and `span_id` if available.
+```ts
+import { getTracer } from '@sebspark/otel'
+
+const tracer = getTracer()
+
+await tracer.withTrace('trace.name', async (span) => {
+  span.setAttribute('user.id', '123')
+  // do something...
+})
+```
+
+If the callback throws:
+- Span is marked as `ERROR`
+- Exception is recorded
+- Span is ended properly
+
+Synchronous variant:
 
 ```ts
-import { getLogger } from '@sebspark/otel'
+tracer.withTraceSync('init.config', (span) => {
+  // synchronous code
+  span.setStatus({ code: SpanStatusCode.OK })
+})
+```
 
-const logger = getLogger()
+Nested:
+
+```ts
+await tracer.withTrace('trace.name', async (span1) => {
+  span1.setAttribute('user.id', '123')
+  
+  await tracer.withTrace('trace.name2', span1, async (span2) => {
+    // do stuff
+  })
+})
+```
+
+Manual span usage:
 
-logger.debug('message')
-logger.info('message')
-logger.warn('message')
-logger.error('message')
+```ts
+const span = tracer.startSpan('manual-operation')
+span.setAttribute('manual', true)
+// work...
+span.end()
 ```
 
 ---
 
 ### Metrics
 
-You can use the metrics API to create and export custom application-level metrics.
-
 ```ts
 import { getMeter } from '@sebspark/otel'
 
 const meter = getMeter()
 
 const counter = meter.createCounter('http_requests_total', {
-  description: 'Total number of HTTP requests'
+  description: 'Total number of HTTP requests',
 })
 
 counter.add(1, {
   route: '/api/hello',
-  method: 'GET'
+  method: 'GET',
 })
 ```
 
 ---
 
-### Tracing
+## Configure for cloud use (with OpenTelemetry Collector)
 
-The tracer helps you capture **distributed traces** across services and automatically links logs with `trace_id` and `span_id` when called inside a span context.
+When deployed to **Cloud Run**, **GKE**, or other cloud environments, telemetry automatically exports to your configured **OpenTelemetry Collector**.
 
-#### Get a tracer
+Set these environment variables:
 
-```ts
-import { getTracer } from '@sebspark/otel'
+| Variable                      | Description                     | Example                       |
+|-------------------------------|---------------------------------|-------------------------------|
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Collector endpoint              | `http://otel-collector:4318`  |
+| `OTEL_SERVICE_NAME`           | Override detected service name  | `trade-api`                   |
+| `OTEL_SERVICE_VERSION`        | Version of this instance        | `1.2.3`                       |
 
-const tracer = getTracer()
-```
+Additional GCP/Kubernetes context is auto‑detected:
 
-Optionally override the service name:
+| Env Variable              | Attribute Key         | Example           |
+|---------------------------|-----------------------|-------------------|
+| `K_SERVICE`               | `cloud.run.service`   | `trade-api`       |
+| `K_REVISION`              | `cloud.run.revision`  | `trade-api-v15`   |
+| `POD_NAME`                | `k8s.pod_name`        | `api-1234`        |
+| `KUBERNETES_SERVICE_HOST` | `cloud.orchestrator`  | `kubernetes`      |
+| `GCP_PROJECT`             | `cloud.account.id`    | `my-gcp-project`  |
 
-```ts
-const tracer = getTracer('my-custom-service')
-```
+---
 
-#### Automatically wrap logic in a span
+## Configure for local use (dev logging)
 
-**Async**
+In development, `@sebspark/otel` outputs human-readable **logs**, **spans**, and **metrics** directly to the console.
 
-```ts
-await tracer.withTrace('trace name', async (span) => {
-  // span is active here
-  span.setAttribute('custom.attribute', 'value')
-})
-```
+---
+
+### Environment variables
+
+| Variable       | Affects | Values                                   | Description                                                                             |
+|----------------|---------|------------------------------------------|-----------------------------------------------------------------------------------------|
+| `LOG_LEVEL`    | Logs    | `debug,info,warn,error`                  | Minimum severity to print                                                               |
+| `SPAN_LEVEL`   | Traces  | `OK`, `ERROR`, `UNSET` (comma-separated) | Only trees containing **at least one** span with one of these statuses will be printed  |
+| `METRIC_FILTER`| Metrics | Glob patterns (comma-separated)          | Only metrics matching any of the patterns are shown                                     |
+
+---
 
-**Sync**
+### Logs
+
+Filtered by `LOG_LEVEL`:
+
+```sh
+LOG_LEVEL=warn yarn dev
+```
 
 ```ts
-tracer.withTraceSync('init.config', () => {
-  // synchronous logic
-})
+⚠️  [trade-api@1.2.3] GET /orders/limit-exceeded      WARN    trace_id=abc123 span_id=def456
+❌  [trade-api@1.2.3] Order validation failed         ERROR   trace_id=abc123 span_id=def456
 ```
 
-**Errors**
+---
 
-If an error is thrown during an auto traced function:
+### Spans
 
-- The span is marked with `SpanStatusCode.ERROR`
-- The error is recorded via `span.recordException()`
-- The span is always ended correctly
+Filtered by `SPAN_LEVEL` — the entire span **tree** is printed only if **at least one** span in the tree matches the status.
 
-#### Manual control
+```sh
+SPAN_LEVEL=ERROR yarn dev
+```
 
 ```ts
-const span = tracer.startSpan('manual-task')
-span.setAttribute('manual', true)
-// do work...
-span.end()
+[test@1.0.0] 12:00:00.000
+└─ express                 ████████████████████                OK     (0 ms–1.00 s)
+   └─ middleware:auth      ███████                             OK     (0 ms–0.20 s)
+   └─ handler:getUser      ████████████████████                ERROR  (0 ms–1.00 s)
+```
+
+```sh
+SPAN_LEVEL=OK,ERROR yarn dev
 ```
 
-#### Nested span attributes
+```ts
+[test@1.0.0] 12:01:00.000
+└─ express                 ████████████████████                OK     (0 ms–1.00 s)
+   └─ middleware:auth      ███████                             OK     (0 ms–0.20 s)
+```
 
-Any span created via `withTrace` or `withTraceSync` will automatically inherit these attributes from the parent (if present):
+---
 
-- `parent_service_name`
-- `parent_span_name`
+### 📈 Metrics
 
-This makes cross‑service tracing easier to follow in tools like **Google Cloud Trace**, **Jaeger** or **Grafana Tempo**.
+Filtered by `METRIC_FILTER`:
+
+```sh
+METRIC_FILTER=http.*,db.* yarn dev
+```
+
+```ts
+📊 [trade-api@1.2.3] 12:00:00.000  📊  express http.server.duration 240ms {route=/api/hello method=GET}
+📊 [trade-api@1.2.3] 12:00:01.000  📊  pg db.query.count 1 {query=SELECT * FROM users}
+```

package/dist/index.d.mts

@@ -13,19 +13,23 @@ declare function getLogger(serviceOverride?: string, extraAttrs?: Attrs): {
     emergency: (msg: string, attrs?: Attrs) => void;
 };
 
-declare function getMeter(serviceOverride?: string): _opentelemetry_api.Meter;
+declare function getMeter(componentNameOverride?: string): _opentelemetry_api.Meter;
 
 type OtelTracer = ReturnType<typeof trace.getTracer>;
 type Span = ReturnType<OtelTracer['startSpan']>;
-type Func<T> = (span?: Span) => Promise<T> | T;
-type SyncFunc<T> = (span?: Span) => T;
+type Func<T> = (span: Span) => Promise<T> | T;
+type SyncFunc<T> = (span: Span) => T;
 type WithTrace = {
     <T>(name: string, fn: Func<T>): Promise<T>;
     <T>(name: string, options: SpanOptions, fn: Func<T>): Promise<T>;
+    <T>(name: string, parent: Span, fn: Func<T>): Promise<T>;
+    <T>(name: string, options: SpanOptions, parent: Span, fn: Func<T>): Promise<T>;
 };
 type WithTraceSync = {
     <T>(name: string, fn: SyncFunc<T>): T;
     <T>(name: string, options: SpanOptions, fn: SyncFunc<T>): T;
+    <T>(name: string, parent: Span, fn: SyncFunc<T>): T;
+    <T>(name: string, options: SpanOptions, parent: Span, fn: SyncFunc<T>): T;
 };
 /**
  * Extended tracer with helper methods for span-wrapped execution
@@ -41,6 +45,6 @@ interface Tracer extends OtelTracer {
  * @param serviceOverride - Optional override for service name
  * @returns Tracer with helpers
  */
-declare function getTracer(serviceOverride?: string): Tracer;
+declare function getTracer(componentNameOverride?: string): Tracer;
 
 export { getLogger, getMeter, getTracer };

package/dist/index.d.ts

@@ -13,19 +13,23 @@ declare function getLogger(serviceOverride?: string, extraAttrs?: Attrs): {
     emergency: (msg: string, attrs?: Attrs) => void;
 };
 
-declare function getMeter(serviceOverride?: string): _opentelemetry_api.Meter;
+declare function getMeter(componentNameOverride?: string): _opentelemetry_api.Meter;
 
 type OtelTracer = ReturnType<typeof trace.getTracer>;
 type Span = ReturnType<OtelTracer['startSpan']>;
-type Func<T> = (span?: Span) => Promise<T> | T;
-type SyncFunc<T> = (span?: Span) => T;
+type Func<T> = (span: Span) => Promise<T> | T;
+type SyncFunc<T> = (span: Span) => T;
 type WithTrace = {
     <T>(name: string, fn: Func<T>): Promise<T>;
     <T>(name: string, options: SpanOptions, fn: Func<T>): Promise<T>;
+    <T>(name: string, parent: Span, fn: Func<T>): Promise<T>;
+    <T>(name: string, options: SpanOptions, parent: Span, fn: Func<T>): Promise<T>;
 };
 type WithTraceSync = {
     <T>(name: string, fn: SyncFunc<T>): T;
     <T>(name: string, options: SpanOptions, fn: SyncFunc<T>): T;
+    <T>(name: string, parent: Span, fn: SyncFunc<T>): T;
+    <T>(name: string, options: SpanOptions, parent: Span, fn: SyncFunc<T>): T;
 };
 /**
  * Extended tracer with helper methods for span-wrapped execution
@@ -41,6 +45,6 @@ interface Tracer extends OtelTracer {
  * @param serviceOverride - Optional override for service name
  * @returns Tracer with helpers
  */
-declare function getTracer(serviceOverride?: string): Tracer;
+declare function getTracer(componentNameOverride?: string): Tracer;
 
 export { getLogger, getMeter, getTracer };