@kabran-tecnologia/kabran-config 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kabran-tecnologia/kabran-config",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Shared quality configurations, enforcement scripts, and CI/CD tooling for Kabran projects",
   "author": "Kabran",
   "license": "MIT",

package/src/scripts/ci/ci-core.sh

@@ -27,6 +27,8 @@ NC='\033[0m'
 declare -a ERRORS=()
 declare -a STEP_RESULTS=()
 CI_START_TIME=""
+CI_TRACE_ID=""
+CI_SPAN_ID=""
 
 # ==============================================================================
 # Logging Functions
@@ -58,6 +60,128 @@ log_debug() {
   fi
 }
 
+# ==============================================================================
+# Trace Context Functions (OpenTelemetry W3C Trace Context)
+# ==============================================================================
+
+# Generate a random hex string of specified length
+# Usage: generate_hex_string 32
+generate_hex_string() {
+  local length="${1:-32}"
+  # Try multiple methods for generating random hex
+  if command -v openssl &>/dev/null; then
+    openssl rand -hex "$((length / 2))" 2>/dev/null
+  elif [ -r /dev/urandom ]; then
+    head -c "$((length / 2))" /dev/urandom | od -An -tx1 | tr -d ' \n' | head -c "$length"
+  else
+    # Fallback: use date + process ID + random
+    local seed="$$$(date +%s%N 2>/dev/null || date +%s)"
+    echo "$seed" | md5sum 2>/dev/null | head -c "$length" || echo "$seed" | head -c "$length"
+  fi
+}
+
+# Generate a W3C trace ID (32 hex chars = 128 bits)
+# Usage: generate_trace_id
+generate_trace_id() {
+  generate_hex_string 32
+}
+
+# Generate a W3C span ID (16 hex chars = 64 bits)
+# Usage: generate_span_id
+generate_span_id() {
+  generate_hex_string 16
+}
+
+# Initialize trace context for the CI run
+# Sets TRACEPARENT env var if not already set
+# Format: 00-{trace_id}-{span_id}-{flags}
+# Usage: setup_trace_context
+setup_trace_context() {
+  # Check if trace context already exists from environment
+  if [ -n "${TRACEPARENT:-}" ]; then
+    log_debug "Using existing TRACEPARENT: $TRACEPARENT"
+    # Extract trace_id and span_id from existing TRACEPARENT
+    CI_TRACE_ID=$(echo "$TRACEPARENT" | cut -d'-' -f2)
+    CI_SPAN_ID=$(echo "$TRACEPARENT" | cut -d'-' -f3)
+    return 0
+  fi
+
+  # Check for direct trace ID from environment
+  if [ -n "${OTEL_TRACE_ID:-}" ]; then
+    log_debug "Using OTEL_TRACE_ID: $OTEL_TRACE_ID"
+    CI_TRACE_ID="$OTEL_TRACE_ID"
+    CI_SPAN_ID=$(generate_span_id)
+    TRACEPARENT="00-${CI_TRACE_ID}-${CI_SPAN_ID}-01"
+    export TRACEPARENT
+    return 0
+  fi
+
+  # Check for GitHub Actions run ID (use as fallback correlation)
+  if [ -n "${GITHUB_RUN_ID:-}" ]; then
+    log_debug "Using GitHub run ID for trace correlation"
+    # Create deterministic trace_id from GitHub run info
+    local gh_seed="${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT:-1}"
+    CI_TRACE_ID=$(echo "$gh_seed" | md5sum | head -c 32)
+    CI_SPAN_ID=$(generate_span_id)
+    TRACEPARENT="00-${CI_TRACE_ID}-${CI_SPAN_ID}-01"
+    export TRACEPARENT
+    log_debug "Generated TRACEPARENT from GitHub: $TRACEPARENT"
+    return 0
+  fi
+
+  # Generate new trace context for local execution
+  log_debug "Generating new trace context for local CI run"
+  CI_TRACE_ID=$(generate_trace_id)
+  CI_SPAN_ID=$(generate_span_id)
+  TRACEPARENT="00-${CI_TRACE_ID}-${CI_SPAN_ID}-01"
+  export TRACEPARENT
+
+  log_info "Trace ID: ${CI_TRACE_ID:0:8}... (local)"
+  log_debug "Full TRACEPARENT: $TRACEPARENT"
+  return 0
+}
+
+# Get the current trace ID
+# Usage: get_trace_id
+get_trace_id() {
+  echo "${CI_TRACE_ID:-}"
+}
+
+# Get trace context info for metadata
+# Usage: get_trace_context_json
+get_trace_context_json() {
+  local trace_id="${CI_TRACE_ID:-}"
+  local span_id="${CI_SPAN_ID:-}"
+  local traceparent="${TRACEPARENT:-}"
+
+  if [ -z "$trace_id" ]; then
+    echo "null"
+    return
+  fi
+
+  # Determine source of trace context
+  local source="local"
+  if [ -n "${GITHUB_RUN_ID:-}" ]; then
+    source="github"
+  elif [ -n "${OTEL_TRACE_ID:-}" ]; then
+    source="otel_env"
+  elif [ -n "${TRACEPARENT:-}" ] && [ "${CI_TRACE_ID:-}" != "$(echo "$TRACEPARENT" | cut -d'-' -f2)" ]; then
+    source="external"
+  fi
+
+  jq -n \
+    --arg trace_id "$trace_id" \
+    --arg span_id "$span_id" \
+    --arg traceparent "$traceparent" \
+    --arg source "$source" \
+    '{
+      trace_id: $trace_id,
+      span_id: $span_id,
+      traceparent: $traceparent,
+      source: $source
+    }'
+}
+
 # ==============================================================================
 # Version Compatibility Check
 # ==============================================================================
@@ -432,6 +556,10 @@ export_ci_data() {
   # Get scope
   local scope="${CI_SCOPE:-all}"
 
+  # Get trace context
+  local trace_context
+  trace_context=$(get_trace_context_json)
+
   # Generate intermediate data file for Node.js generator
   jq -n \
     --argjson steps "$steps_json" \
@@ -441,6 +569,7 @@ export_ci_data() {
     --arg finished_at "$now" \
     --arg project_name "$project_name" \
     --arg scope "$scope" \
+    --argjson trace_context "$trace_context" \
     '{
       steps: $steps,
       errors: $errors,
@@ -454,7 +583,8 @@ export_ci_data() {
       },
       metadata: {
         scope: $scope
-      }
+      },
+      trace_context: $trace_context
     }' > "$output_file"
 
   log_debug "CI data exported to: $output_file"

package/src/scripts/ci/ci-runner.sh

@@ -171,6 +171,9 @@ if [ "$CI_SCOPE" != "all" ]; then
 fi
 echo ""
 
+# Setup trace context (generates trace_id if not provided externally)
+setup_trace_context
+
 # Start timing
 ci_start
 

package/src/scripts/generate-ci-result.mjs

@@ -177,8 +177,9 @@ export function generateCiResult(input) {
   // Determine exit code
   const exitCode = executionStats.steps_failed > 0 ? 1 : 0
 
-  // Get trace ID if available
-  const traceId = getTraceId()
+  // Get trace ID - prefer trace_context from input (shell-generated) over env vars
+  const traceContext = input.trace_context || {}
+  const traceId = traceContext.trace_id || getTraceId()
 
   // Build meta object
   const meta = {
@@ -198,7 +199,19 @@ export function generateCiResult(input) {
   // Build extensions with telemetry if trace_id exists
   const extensions = { ...(metadata.extensions || {}) }
   if (traceId) {
-    extensions.telemetry = buildTelemetryExtension(traceId)
+    // Count errors from failed steps
+    const errorsRecorded = executionStats.steps_failed || 0
+
+    extensions.telemetry = buildTelemetryExtension(traceId, {
+      errorsRecorded,
+      // spans_exported remains 0 until we implement actual OTel export (GAP-004/Q12)
+      spansExported: 0,
+    })
+
+    // Add trace source info if available
+    if (traceContext.source) {
+      extensions.telemetry.trace_source = traceContext.source
+    }
   }
 
   // Build result object

package/src/telemetry/README.md

@@ -0,0 +1,407 @@
+# @kabran-tecnologia/kabran-config/telemetry
+
+Unified telemetry package for Kabran projects using OpenTelemetry.
+
+## Features
+
+- **Multi-runtime support**: Node.js, Frontend (Browser), Edge/Serverless
+- **OpenTelemetry integration**: W3C Trace Context, OTLP export
+- **Zero-config defaults**: Works out of the box with sensible defaults
+- **Structured logging**: Logger with automatic trace correlation
+- **Tree-shakeable**: Import only what you need
+
+## Installation
+
+The telemetry modules are included in `@kabran-tecnologia/kabran-config`. Install the package and the required OpenTelemetry peer dependencies:
+
+```bash
+# Install kabran-config
+npm install @kabran-tecnologia/kabran-config
+
+# Install required peer dependencies (pick based on your runtime)
+
+# For Node.js:
+npm install @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions
+
+# For Frontend:
+npm install @opentelemetry/api @opentelemetry/sdk-trace-web @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/instrumentation-fetch @opentelemetry/instrumentation-document-load @opentelemetry/instrumentation-user-interaction
+
+# For Edge/Serverless:
+npm install @opentelemetry/api @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions
+```
+
+## Quick Start
+
+### Node.js (Express/Fastify)
+
+```javascript
+// instrumentation.js - Import this FIRST in your app
+import { initTelemetry, telemetryMiddleware, shutdownTelemetry } from '@kabran-tecnologia/kabran-config/telemetry/node'
+
+// Initialize telemetry
+initTelemetry({
+  serviceName: 'my-api',
+  serviceVersion: '1.0.0',
+})
+
+// In your Express app
+import express from 'express'
+const app = express()
+
+// Add telemetry middleware (creates spans for each request)
+app.use(telemetryMiddleware())
+
+app.get('/api/users', (req, res) => {
+  // Your handler - automatically traced
+  res.json({ users: [] })
+})
+
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await shutdownTelemetry()
+  process.exit(0)
+})
+```
+
+### Frontend (React/Vite)
+
+```typescript
+// main.tsx
+import { initTelemetry } from '@kabran-tecnologia/kabran-config/telemetry/frontend'
+
+// Initialize before rendering
+initTelemetry({
+  serviceName: 'my-frontend',
+  serviceVersion: '1.0.0',
+  // Optional: customize which events to trace
+  instrumentation: {
+    userInteractionEvents: ['click', 'submit'],
+  },
+})
+
+// Your React app renders normally
+import { createRoot } from 'react-dom/client'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(<App />)
+```
+
+### Edge/Serverless (Supabase Functions)
+
+```typescript
+// supabase/functions/my-function/index.ts
+import { withTelemetry, traceSupabaseQuery } from '@kabran-tecnologia/kabran-config/telemetry/edge'
+import { createClient } from '@supabase/supabase-js'
+
+const supabase = createClient(
+  Deno.env.get('SUPABASE_URL')!,
+  Deno.env.get('SUPABASE_ANON_KEY')!
+)
+
+// Wrap your handler with telemetry
+Deno.serve(withTelemetry(
+  {
+    serviceName: 'my-edge-function',
+    serviceVersion: '1.0.0',
+  },
+  async (req) => {
+    // Trace Supabase queries
+    const { data, error } = await traceSupabaseQuery(
+      'select-users',
+      () => supabase.from('users').select('*')
+    )
+
+    return new Response(JSON.stringify({ data, error }), {
+      headers: { 'Content-Type': 'application/json' },
+    })
+  }
+))
+```
+
+## Structured Logging
+
+The logger automatically includes trace context in log output:
+
+```javascript
+import { createLogger } from '@kabran-tecnologia/kabran-config/telemetry/logger'
+
+const log = createLogger()
+
+log.info('User logged in', { userId: '123' })
+// Output (JSON in production):
+// {"level":"info","message":"User logged in","userId":"123","trace_id":"abc123...","span_id":"def456...","timestamp":"2024-01-13T..."}
+
+// Output (pretty in development):
+// 2024-01-13T12:00:00.000Z [INFO] User logged in [trace:abc123...] {"userId":"123"}
+```
+
+### Span-bound Logger
+
+```javascript
+import { trace } from '@opentelemetry/api'
+import { createSpanLogger } from '@kabran-tecnologia/kabran-config/telemetry/logger'
+
+const span = trace.getActiveSpan()
+const log = createSpanLogger(span)
+
+log.info('Processing order', { orderId: '456' })
+// Logs are also added as span events for visibility in traces
+```
+
+## Configuration
+
+### Environment Variables
+
+All configuration can be set via environment variables:
+
+```bash
+# Core
+SERVICE_NAME=my-service              # Required: Your service name
+SERVICE_VERSION=1.0.0                # Service version (default: 1.0.0)
+ENVIRONMENT=production               # Environment name (default: from NODE_ENV)
+OTEL_NAMESPACE=kabran                # Service namespace (default: kabran)
+
+# OTLP Exporter
+OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.kabran.com.br  # Collector endpoint
+OTEL_EXPORTER_OTLP_TIMEOUT=10000     # Export timeout in ms (default: 10000)
+
+# Sampling
+OTEL_SAMPLE_RATE=0.1                 # Sampling rate 0.0-1.0 (default: 0.1 = 10%)
+
+# Enable/Disable
+OTEL_ENABLED=true                    # Enable telemetry (default: true in production)
+
+# Logger
+OTEL_LOG_TRACE_ID_LENGTH=8           # Trace ID length in logs (default: 8)
+NO_COLOR=1                           # Disable ANSI colors in logs
+```
+
+### Programmatic Configuration
+
+```javascript
+import { initTelemetry } from '@kabran-tecnologia/kabran-config/telemetry/node'
+
+initTelemetry({
+  // Required
+  serviceName: 'my-service',
+
+  // Optional (all have sensible defaults)
+  serviceVersion: '1.0.0',
+  environment: 'production',
+  endpoint: 'https://otel.kabran.com.br',
+  sampleRate: 0.1,
+  enabled: true,
+
+  // Resource attributes (added to all spans)
+  resourceAttributes: {
+    'deployment.environment': 'production',
+    'service.instance.id': process.env.POD_NAME,
+  },
+
+  // Batch processor settings (Node.js only)
+  batchProcessor: {
+    maxQueueSize: 2048,
+    maxExportBatchSize: 512,
+    scheduledDelayMillis: 5000,
+  },
+})
+```
+
+## Module Reference
+
+### `telemetry/node`
+
+For Node.js servers and long-running processes.
+
+```javascript
+import {
+  initTelemetry,      // Initialize the tracer
+  shutdownTelemetry,  // Graceful shutdown
+  telemetryMiddleware,// Express/Fastify middleware
+  isInitialized,      // Check if initialized
+  getTracer,          // Get the tracer instance
+  getConfig,          // Get resolved config
+} from '@kabran-tecnologia/kabran-config/telemetry/node'
+```
+
+### `telemetry/frontend`
+
+For browser applications (React, Vue, vanilla JS).
+
+```javascript
+import {
+  initTelemetry,      // Initialize the tracer
+  shutdownTelemetry,  // Flush pending spans
+  isInitialized,      // Check if initialized
+  getTracer,          // Get the tracer instance
+  getConfig,          // Get resolved config
+} from '@kabran-tecnologia/kabran-config/telemetry/frontend'
+```
+
+### `telemetry/edge`
+
+For Edge Functions and serverless (Supabase, Deno Deploy, Cloudflare Workers).
+
+```javascript
+import {
+  withTelemetry,      // Handler wrapper with auto-tracing
+  traceSupabaseQuery, // Trace Supabase queries
+  shutdownTelemetry,  // Flush pending spans
+  isInitialized,      // Check if initialized
+  getConfig,          // Get resolved config
+} from '@kabran-tecnologia/kabran-config/telemetry/edge'
+```
+
+### `telemetry/logger`
+
+Structured logger with trace correlation.
+
+```javascript
+import {
+  createLogger,       // Create a logger instance
+  createSpanLogger,   // Create a span-bound logger
+  log,                // Default logger instance
+  getTraceContext,    // Get current trace context
+} from '@kabran-tecnologia/kabran-config/telemetry/logger'
+```
+
+### `telemetry/config`
+
+Configuration utilities.
+
+```javascript
+import {
+  defineTelemetryConfig,  // Create a type-safe config
+  resolveConfig,          // Resolve config with defaults and env vars
+  validateConfig,         // Validate config object
+  detectEnabled,          // Check if telemetry should be enabled
+} from '@kabran-tecnologia/kabran-config/telemetry/config'
+```
+
+### `telemetry/shared`
+
+Shared utilities and types.
+
+```javascript
+import {
+  setAttributes,         // Set multiple span attributes
+  formatDuration,        // Format milliseconds to human-readable
+  generateInvocationId,  // Generate unique invocation ID
+  safeWarn,              // Safe console.warn
+  safeLog,               // Safe console.log
+} from '@kabran-tecnologia/kabran-config/telemetry/shared'
+```
+
+## Integration with Kosmos Observability
+
+This package is designed to work with the Kosmos observability stack:
+
+- **Traces** → Grafana Tempo
+- **Logs** → Grafana Loki (via stdout/Promtail or direct export)
+- **Metrics** → Prometheus (planned, see [GAP-006])
+
+Default endpoint: `https://otel.kabran.com.br`
+
+### Viewing Traces
+
+1. Open Grafana at your Kosmos instance
+2. Go to Explore → Select Tempo
+3. Search by service name or trace ID
+
+## Best Practices
+
+### 1. Initialize Early
+
+Initialize telemetry as early as possible in your application:
+
+```javascript
+// This should be the FIRST import
+import './instrumentation.js'
+
+// Then your app code
+import express from 'express'
+```
+
+### 2. Use Meaningful Span Names
+
+```javascript
+// Good
+span.updateName('user.create')
+span.updateName('order.process')
+
+// Bad
+span.updateName('handler')
+span.updateName('function1')
+```
+
+### 3. Add Relevant Attributes
+
+```javascript
+import { trace } from '@opentelemetry/api'
+
+const span = trace.getActiveSpan()
+span?.setAttributes({
+  'user.id': userId,
+  'order.id': orderId,
+  'order.total': total,
+})
+```
+
+### 4. Handle Errors Properly
+
+```javascript
+import { trace, SpanStatusCode } from '@opentelemetry/api'
+
+try {
+  // Your code
+} catch (error) {
+  const span = trace.getActiveSpan()
+  span?.recordException(error)
+  span?.setStatus({ code: SpanStatusCode.ERROR, message: error.message })
+  throw error
+}
+```
+
+### 5. Graceful Shutdown
+
+Always flush pending spans before shutdown:
+
+```javascript
+process.on('SIGTERM', async () => {
+  await shutdownTelemetry()
+  process.exit(0)
+})
+```
+
+## Troubleshooting
+
+### Traces not appearing
+
+1. Check `OTEL_ENABLED` is not set to `false`
+2. Verify `SERVICE_NAME` is set
+3. Check network connectivity to the collector endpoint
+4. Verify sampling rate (default is 10%)
+
+### Missing trace correlation in logs
+
+1. Ensure telemetry is initialized before logging
+2. Check that you're within an active span context
+
+### High memory usage
+
+Reduce batch processor queue size:
+
+```javascript
+initTelemetry({
+  serviceName: 'my-service',
+  batchProcessor: {
+    maxQueueSize: 512,  // Lower from default 2048
+  },
+})
+```
+
+## Related Documentation
+
+- [OpenTelemetry JavaScript](https://opentelemetry.io/docs/languages/js/)
+- [W3C Trace Context](https://www.w3.org/TR/trace-context/)
+- [Kosmos Observability Stack](https://github.com/kabran-owner/kosmos/tree/main/services/observability)