@fulmenhq/tsfulmen 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -9,6 +9,96 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **HTTP Server Metrics** (`@fulmenhq/tsfulmen/telemetry/http`) - Type-safe HTTP instrumentation with Crucible v0.2.18 taxonomy
+  - **Core Helpers**:
+    - `recordHttpRequest()` - Records all 5 HTTP metrics with automatic unit conversion (ms → seconds)
+    - `trackActiveRequest()` - Active requests gauge management with cleanup
+    - AppIdentity integration for automatic service label defaults
+  - **Framework Middleware**:
+    - `createHttpMetricsMiddleware()` - Express/Connect-compatible middleware
+    - `createFastifyMetricsPlugin()` - Fastify plugin with hooks
+    - `createBunMetricsHandler()` - Bun.serve fetch handler wrapper
+  - **Metrics Emitted** (Crucible v0.2.18):
+    - `http_requests_total` - Counter with method/route/status/service labels
+    - `http_request_duration_seconds` - Histogram with automatic ms → seconds conversion
+    - `http_request_size_bytes` - Optional request size histogram
+    - `http_response_size_bytes` - Optional response size histogram
+    - `http_active_requests` - Active requests gauge
+  - **Features**:
+    - Configurable route normalizers (prevents cardinality explosion)
+    - Optional body size tracking (performance-conscious, disabled by default)
+    - Custom method/status extractors for framework flexibility
+    - No unsafe TypeScript casts, full type safety
+  - **Documentation**:
+    - Comprehensive HTTP metrics guide with framework examples
+    - Troubleshooting section (6+ common issues with solutions)
+    - Production recommendations and best practices
+    - Framework integration notes (Express, Fastify, Bun, Node.js HTTP)
+  - **Test Coverage**: 40+ tests (100% coverage of helpers module)
+  - **Quality**: All tests passing, typecheck clean, lint clean
+
+- **Logging Middleware & Secure Redaction** (`@fulmenhq/tsfulmen/logging`) - STRUCTURED profile middleware pipeline with secure-by-default redaction
+  - **Middleware Pipeline Support**:
+    - Middleware execution for STRUCTURED and ENTERPRISE profiles
+    - Child loggers inherit parent middleware chain and bindings
+    - Severity adjustment support (middleware can modify event severity)
+    - Middleware chain execution before Pino emission
+  - **Built-in Middleware**:
+    - `RedactSecretsMiddleware` - Enhanced with gofulmen-aligned patterns and field names
+    - `AddFieldsMiddleware` - Inject context fields into log events
+    - `TransformMiddleware` - Custom event transformations
+  - **Helper Function**:
+    - `createStructuredLoggerWithRedaction()` - Secure-by-default structured logger
+    - Default redaction patterns: SECRET\_*, *TOKEN*, *KEY\*, Base64 blobs, emails, credit cards
+    - Default field names (case-insensitive): password, token, apiKey, authorization, secret, cardNumber, cvv, ssn
+    - Customization options: customPatterns, customFields, useDefaultPatterns (opt-out)
+    - File output support with redaction enabled
+  - **Security Model**:
+    - Redaction enabled by default when using helper function
+    - Gofulmen-aligned patterns for cross-language consistency
+    - Case-insensitive field matching (O(1) lookup)
+    - Pattern scanning with 10KB threshold optimization
+  - **Performance**:
+    - Pattern scanning skips strings >10KB to avoid performance degradation
+    - Field-based redaction (O(1)) always applies
+    - Minimal middleware overhead (<5% for typical events)
+    - Pre-compiled regex patterns and lowercase field maps
+  - **Documentation**:
+    - Comprehensive logging README (789 lines) with 35+ code examples
+    - Main README Progressive Logging section with before/after examples
+    - API reference for all middleware types and helper functions
+    - Troubleshooting guide with 4 common scenarios
+    - Migration guide from simple to structured to secure logging
+  - **Test Coverage**: 12 new integration tests (121 total logging tests)
+  - **Quality**: All tests passing (1749 tests), typecheck clean, fully documented
+
+---
+
+## [0.1.10] - 2025-11-17
+
+### Fixed
+
+- **Critical: Signal catalog loading in installed packages** - Fixed path resolution bug that prevented signals catalog from loading when package was installed via npm. The bundled code in `dist/foundry/index.js` was using incorrect relative paths (`../../../config` instead of `../../config`) due to tsup bundling behavior. Added runtime path detection to handle both development (source files) and production (bundled files) contexts.
+- **Pre-publish verification** - Added `scripts/verify-local-install.ts` and `make verify-local-install` target to catch path resolution bugs before publishing. This script packs the package locally, installs it to a temp directory, and tests catalog loading in the installed context.
+
+### Added
+
+- Runtime path detection in signals catalog loader (src/foundry/signals/catalog.ts:23-30)
+- Pre-publish integration test (scripts/verify-local-install.ts)
+- Makefile target `verify-local-install` for pre-publish verification
+
+### Changed
+
+- Signals catalog path resolution now detects whether running from source (`src/`) or dist (`dist/`) and adjusts paths accordingly
+
+---
+
+## [0.1.9] - 2025-11-16 [DEPRECATED - Non-functional]
+
+**⚠️ DO NOT USE**: This version has a critical bug where catalog loading fails in installed packages. Use v0.1.10 or later.
+
+### Added
+
 - **Fulpack Module** (`@fulmenhq/tsfulmen/fulpack`) - Security-first archive operations for TAR, TAR.GZ, ZIP, and GZIP formats
   - **Five Canonical Operations**:
     - `create()` - Create archives from files/directories with configurable compression

package/README.md

@@ -9,19 +9,20 @@ TypeScript Fulmen helper library for enterprise-scale development.
 ## Status
 
 **Lifecycle Phase:** `alpha` (see [`LIFECYCLE_PHASE`](LIFECYCLE_PHASE))
-**Development Status:** ✅ v0.1.9 - Fulpack archives, pathfinder repository root discovery
-**Test Coverage:** 1638 tests passing (100% pass rate)
+**Development Status:** 🚧 v0.1.11 - HTTP server metrics, logging middleware with secure redaction
+**Test Coverage:** 1749 tests passing (100% pass rate)
 
-TSFulmen v0.1.9 adds security-first archive operations (fulpack) for TAR/TAR.GZ/ZIP/GZIP formats and repository root discovery (pathfinder) with boundary enforcement. See [TSFulmen Overview](docs/tsfulmen_overview.md) for roadmap.
+TSFulmen v0.1.11 adds HTTP server metrics with Crucible v0.2.18 taxonomy (Express/Fastify/Bun middleware) and logging middleware pipeline with secure-by-default redaction (gofulmen-aligned patterns). See [TSFulmen Overview](docs/tsfulmen_overview.md) for roadmap.
 
 ## Features
 
 - ✅ **Error Handling** - Schema-backed FulmenError with severity levels (43 tests)
 - ✅ **Telemetry & Metrics** - Counter/gauge/histogram with OTLP export (85 tests)
 - ✅ **Telemetry Instrumentation** - Metrics in config, schema, crucible modules (24 tests)
+- ✅ **HTTP Server Metrics** - Type-safe HTTP instrumentation with Express/Fastify/Bun middleware (40+ tests)
 - ✅ **FulHash** - Fast hashing with XXH3-128 and SHA-256, 22x faster small inputs (157 tests)
 - ✅ **Fulpack** - Archive operations (TAR, TAR.GZ, ZIP, GZIP) with security-first design (20 tests)
-- ✅ **Progressive Logging** - Policy enforcement with Pino profiles (83 tests)
+- ✅ **Progressive Logging** - Policy enforcement with Pino profiles, middleware pipeline, secure redaction (121 tests)
 - ✅ **Crucible Shim** - Typed access to synced schemas, docs, and config defaults (96 tests)
 - ✅ **DocScribe** - Document processing with frontmatter parsing (50+ tests)
 - ✅ **Config Path API** - XDG-compliant configuration directory resolution (26 tests)
@@ -237,6 +238,131 @@ await metrics.flush({
 });
 ```
 
+### HTTP Server Metrics
+
+Type-safe HTTP instrumentation with automatic route normalization and cardinality protection:
+
+```typescript
+import {
+  recordHttpRequest,
+  trackActiveRequest,
+  createHttpMetricsMiddleware,
+} from "@fulmenhq/tsfulmen/telemetry/http";
+
+// Express middleware (automatic instrumentation)
+app.use(
+  createHttpMetricsMiddleware({
+    serviceName: "api-server",
+    routeNormalizer: (req) => req.route?.path || normalizeRoute(req.path),
+    trackBodySizes: true, // Optional: track request/response sizes
+  }),
+);
+
+// Manual instrumentation
+const start = performance.now();
+const release = trackActiveRequest("api-server");
+try {
+  await handleRequest();
+  recordHttpRequest({
+    method: "GET",
+    route: "/users/:id", // Pre-normalized route
+    status: 200,
+    durationMs: performance.now() - start,
+    requestBytes: 512,
+    responseBytes: 2048,
+  });
+} finally {
+  release();
+}
+```
+
+**Metrics emitted** (Crucible v0.2.18 taxonomy):
+
+- `http_requests_total` - Request counter with method/route/status/service labels
+- `http_request_duration_seconds` - Duration histogram (auto-converts ms → seconds)
+- `http_request_size_bytes` - Request size histogram (optional)
+- `http_response_size_bytes` - Response size histogram (optional)
+- `http_active_requests` - Active requests gauge
+
+**⚠️ Critical**: Routes must be normalized to prevent cardinality explosion. Use `normalizeRoute()` or framework route templates. See [HTTP Metrics Guide](src/telemetry/http/README.md).
+
+**Framework support**: Express, Fastify, Bun.serve, Node.js HTTP
+
+### Progressive Logging
+
+TSFulmen provides profile-based logging from simple CLI tools to enterprise observability with secure redaction middleware.
+
+```typescript
+import {
+  createSimpleLogger,
+  createStructuredLogger,
+  createStructuredLoggerWithRedaction,
+} from "@fulmenhq/tsfulmen/logging";
+
+// Simple: Human-readable for CLI tools
+const cli = createSimpleLogger("mycli");
+cli.info("Processing file", { path: "/data/input.csv" });
+
+// Structured: JSON output for APIs
+const api = createStructuredLogger("api-server");
+api.info("Request processed", { requestId: "req-456", duration: 42 });
+
+// Structured + Redaction: Secure by default
+const secure = createStructuredLoggerWithRedaction("auth-service");
+secure.info("User login", {
+  userId: "user-123",
+  email: "user@example.com", // ← Automatically redacted
+  password: "secret123", // ← Automatically redacted
+  apiKey: "sk_live_1234567890", // ← Automatically redacted
+});
+```
+
+**Output** (with redaction):
+
+```json
+{
+  "severity": "INFO",
+  "timestamp": "2025-11-18T12:00:00.000Z",
+  "service": "auth-service",
+  "message": "User login",
+  "userId": "user-123",
+  "email": "[REDACTED]",
+  "password": "[REDACTED]",
+  "apiKey": "[REDACTED]"
+}
+```
+
+**Security Model**: `createStructuredLoggerWithRedaction()` enables redaction by default with gofulmen-aligned patterns for common secrets (passwords, tokens, API keys, emails, credit cards).
+
+**Performance**: Pattern scanning automatically skips strings larger than 10KB to avoid performance impact on large payloads. Field-based redaction (O(1) lookup) always applies.
+
+**Customization**:
+
+```typescript
+// Add organization-specific patterns
+const logger = createStructuredLoggerWithRedaction("api-server", {
+  customPatterns: [/INTERNAL_ID_\d+/g, /CUST_[A-Z0-9]{10}/g],
+  customFields: ["internalKey", "customerSecret"],
+});
+
+// Opt-out of defaults for full control
+const customLogger = createStructuredLoggerWithRedaction("api-server", {
+  useDefaultPatterns: false,
+  customPatterns: [/MY_SECRET/g],
+});
+```
+
+**Child Loggers**: Child loggers inherit middleware and bindings from parent.
+
+```typescript
+const parent = createStructuredLoggerWithRedaction("api-server");
+const child = parent.child({ requestId: "req-789" });
+
+child.info("Processing", { password: "secret" }); // ← Still redacted!
+```
+
+See [Logging README](src/logging/README.md) for complete documentation including middleware, profiles, and policy enforcement.
+
 ### Config Path API
 
 ```typescript

package/config/crucible-ts/devsecops/secrets/v1.0.0/defaults.yaml

@@ -8,63 +8,148 @@
 # WARNING: This is a SAMPLE file with anonymized/fake secrets for demonstration.
 #          DO NOT commit real secrets to version control in plaintext.
 #          Use encryption (fulsecrets encrypt) before committing production secrets.
-schema_version: v1.0.0
-# Example 1: Development Environment (Plaintext)
+# Example 1: Minimal Development Environment (Plaintext)
 # Use case: Local development with non-sensitive test credentials
 # Policy: allow_plain_secrets = true (default)
-
+schema_version: v1.0.0
+env_prefix: APP_
 projects:
   - project_slug: myapp-dev
-    env_prefix: APP_
-    secrets:
-      DATABASE_URL: postgres://localhost:5432/myapp_dev
-      REDIS_URL: redis://localhost:6379/0
-      API_KEY: dev_key_12345_not_real
-      SECRET_TOKEN: dev_secret_abc_not_real
-      LOG_LEVEL: debug
-  - project_slug: myapp-test
-    env_prefix: APP_
-    secrets:
-      DATABASE_URL: postgres://localhost:5432/myapp_test
-      REDIS_URL: redis://localhost:6379/1
-      API_KEY: test_key_67890_not_real
-      SECRET_TOKEN: test_secret_xyz_not_real
-      LOG_LEVEL: info
+    credentials:
+      DATABASE_URL:
+        type: password
+        value: postgres://localhost:5432/myapp_dev
+      REDIS_URL:
+        type: password
+        value: redis://localhost:6379/0
+      API_KEY:
+        type: api_key
+        value: dev_key_12345_not_real
+      SECRET_TOKEN:
+        type: token
+        value: dev_secret_abc_not_real
+      LOG_LEVEL:
+        type: password
+        value: debug
 policies:
   allow_plain_secrets: true # OK for development
 
-# Example 2: Multi-Project Configuration (Plaintext)
-# Use case: Monorepo with multiple services sharing some secrets
-# Pattern: Project slugs identify service + environment
+# Example 2: Full-Featured Credentials with Metadata & Rotation
+# Use case: Production secrets with lifecycle tracking and rotation policies
+# Pattern: Rich credential objects with type, metadata, rotation
+---
+schema_version: v1.0.0
+description: |
+  Production secrets for MyApp platform
+  Contact: platform-team@example.com
+  Last updated: 2025-11-17
+env_prefix: PROD_
+projects:
+  - project_slug: backend_api
+    description: Backend API services
+    credentials:
+      STRIPE_API_KEY:
+        type: api_key
+        value: sk_live_abc123def456_not_real
+        description: Live Stripe API key for payment processing
+        metadata:
+          created: "2025-01-15T10:00:00Z"
+          expires: "2026-01-15T10:00:00Z"
+          purpose: payment-processing
+          tags:
+            - payment
+            - critical
+            - pci-scope
+          owner: payments-team
+        rotation:
+          interval: 90d
+          method: auto
+      DATABASE_PASSWORD:
+        type: password
+        value: super_secure_password_not_real
+        description: Primary PostgreSQL database password
+        metadata:
+          created: "2025-01-01T00:00:00Z"
+          expires: "2025-12-31T23:59:59Z"
+          purpose: primary-database
+          tags:
+            - database
+            - critical
+          owner: platform-team
+        rotation:
+          interval: 30d
+          method: manual
+      JWT_SECRET:
+        type: token
+        value: bearer_token_abc123_not_real
+        description: JWT signing secret for authentication
+        metadata:
+          purpose: authentication
+          tags:
+            - auth
+            - critical
+      REDIS_PASSWORD:
+        type: password
+        value: redis_password_xyz789_not_real
+        description: Redis cache password
+
+# Example 3: Multi-Project with External References
+# Use case: Monorepo with multiple services, some credentials from Vault
+# Pattern: Mix of inline values and external references (vault://, aws-secrets://)
 ---
 schema_version: v1.0.0
 projects:
   - project_slug: api-staging
-    secrets:
-      DATABASE_URL: postgres://staging-db.internal:5432/api
-      REDIS_URL: redis://staging-cache.internal:6379
-      JWT_SECRET: staging_jwt_secret_abc123_not_real
-      API_KEY: sk_staging_api_key_not_real
-      SENTRY_DSN: https://fake@sentry.io/staging
+    credentials:
+      DATABASE_URL:
+        type: password
+        ref: vault://secrets/staging/db-url
+        description: Database URL from HashiCorp Vault
+      REDIS_URL:
+        type: password
+        value: redis://staging-cache.internal:6379
+      JWT_SECRET:
+        type: token
+        value: staging_jwt_secret_abc123_not_real
+      API_KEY:
+        type: api_key
+        value: sk_staging_api_key_not_real
+      SENTRY_DSN:
+        type: password
+        value: https://fake@sentry.io/staging
   - project_slug: worker-staging
-    secrets:
-      DATABASE_URL: postgres://staging-db.internal:5432/api # Shared DB
-      QUEUE_URL: amqp://staging-queue.internal:5672
-      WORKER_TOKEN: staging_worker_token_xyz789_not_real
-      SENTRY_DSN: https://fake@sentry.io/staging
-  - project_slug: frontend-staging
-    env_prefix: VITE_ # Frontend framework convention
-    secrets:
-      API_URL: https://api-staging.example.com
-      ANALYTICS_KEY: staging_analytics_key_not_real
-      SENTRY_DSN: https://fake@sentry.io/staging
+    credentials:
+      DATABASE_URL:
+        type: password
+        ref: vault://secrets/staging/db-url # Shared reference
+      QUEUE_URL:
+        type: password
+        value: amqp://staging-queue.internal:5672
+      WORKER_TOKEN:
+        type: token
+        value: staging_worker_token_xyz789_not_real
+      SENTRY_DSN:
+        type: password
+        value: https://fake@sentry.io/staging
+  - project_slug: frontend_staging
+    env_prefix: VITE_ # Override global prefix for frontend
+    credentials:
+      API_URL:
+        type: password
+        value: https://api-staging.example.com
+      ANALYTICS_KEY:
+        type: api_key
+        value: staging_analytics_key_not_real
+      SENTRY_DSN:
+        type: password
+        value: https://fake@sentry.io/staging
 
-# Example 3: Production Environment (Encrypted - GPG)
+# Example 4: Production Environment (Encrypted - GPG)
 # Use case: Production secrets encrypted with GPG for team access
 # Policy: allow_plain_secrets = false (enforce encryption)
 #
 # How to create:
-#   1. Create plaintext file with real secrets
+#   1. Create plaintext file with real secrets (using credential objects)
 #   2. Run: fulsecrets encrypt secrets.yaml --gpg-key team@example.com
 #   3. Commit encrypted file to version control
 #
@@ -82,10 +167,18 @@ encryption:
 # When decrypted, it contains:
 #   projects:
 #     - project_slug: myapp-prod
-#       secrets:
-#         DATABASE_URL: postgres://prod-db.example.com:5432/myapp
-#         API_KEY: sk_live_real_production_key
-#         ...etc
+#       credentials:
+#         DATABASE_URL:
+#           type: password
+#           value: postgres://prod-db.example.com:5432/myapp
+#         API_KEY:
+#           type: api_key
+#           value: sk_live_real_production_key
+#           metadata:
+#             expires: "2026-01-01T00:00:00Z"
+#           rotation:
+#             interval: 90d
+#             method: auto
 ciphertext: |
   -----BEGIN PGP MESSAGE-----
 
@@ -95,7 +188,7 @@ ciphertext: |
 policies:
   allow_plain_secrets: false # Enforce encryption for production
 
-# Example 4: Production Environment (Encrypted - age)
+# Example 5: Production Environment (Encrypted - age)
 # Use case: Modern encryption with age instead of GPG
 # Pattern: Same as GPG but using age public/private key pairs
 #
@@ -120,7 +213,7 @@ ciphertext: |
 policies:
   allow_plain_secrets: false
 
-# Example 5: Passphrase-Based Encryption (Simplest)
+# Example 6: Passphrase-Based Encryption (Simplest)
 # Use case: Solo developer or small team with shared passphrase
 # Pattern: No key management needed, just a strong passphrase
 #
@@ -151,44 +244,70 @@ policies:
 
 # Best Practices & Security Notes:
 #
-# 1. NEVER commit plaintext production secrets to version control
+# 1. Credential Types:
+#    - api_key: External service keys (Stripe, GitHub, AWS) - masked as "sk_live_...xyz"
+#    - token: Auth tokens, JWTs, bearer tokens - masked as "...1234"
+#    - password: Passwords, passphrases, DB URLs - fully redacted "***REDACTED***"
+#
+# 2. Value vs Ref:
+#    - Use 'value' for inline secrets (development, small deployments)
+#    - Use 'ref' for external secret managers (Vault, AWS Secrets Manager)
+#    - Never include both 'value' and 'ref' (mutually exclusive)
+#
+# 3. Metadata & Rotation:
+#    - Add 'metadata.expires' for time-based rotation tracking
+#    - Use 'rotation.interval' to document rotation policy (30d, 90d, 180d)
+#    - Set 'rotation.method: auto' for automated rotation, 'manual' otherwise
+#    - Tag critical credentials with 'tags: [critical]' for monitoring
+#
+# 4. NEVER commit plaintext production secrets to version control:
 #    - Always encrypt production files before git add
 #    - Use .gitignore for *-plain.yaml, *-decrypted.yaml patterns
+#    - Run 'git secrets --scan' or similar tools to prevent leaks
 #
-# 2. Policy enforcement:
+# 5. Policy enforcement:
 #    - Set allow_plain_secrets: false for staging/production
 #    - Keep allow_plain_secrets: true for local development
 #    - Use fulsecrets validate --strict to catch violations
 #
-# 3. Key management:
+# 6. Key management:
 #    - GPG: Good for teams with existing GPG infrastructure
 #    - Age: Modern alternative, simpler key management
 #    - Passphrase: Simplest for solo dev, store in password manager
 #
-# 4. CI/CD integration:
+# 7. CI/CD integration:
 #    - Store passphrases/keys in GitHub Secrets / GitLab CI Variables
 #    - Use environment variables (FULSECRETS_PASSPHRASE) to avoid prompts
 #    - Never echo/print secrets in CI logs
 #
-# 5. Secret rotation:
-#    - Update secrets in plaintext, re-encrypt with same method
+# 8. Secret rotation workflow:
+#    - Decrypt existing file: fulsecrets decrypt secrets.yaml
+#    - Update credential values and metadata.expires timestamps
+#    - Re-encrypt with same method: fulsecrets encrypt secrets.yaml
 #    - For key rotation: decrypt, re-encrypt with new key
-#    - Update encryption.encrypted_at to track rotation
 #
-# 6. Temporary files:
+# 9. Temporary files:
 #    - fulsecrets edit uses secure temp files (/dev/shm, 0600 perms)
 #    - Manual workflow: always rm plaintext files after encryption
 #    - Use shred/srm for sensitive cleanup if available
 #
-# 7. Environment variable naming:
-#    - Use UPPER_SNAKE_CASE for secret keys
-#    - Add env_prefix for namespacing (APP_, SERVICE_, etc.)
-#    - Avoid generic names like "KEY" or "TOKEN" (use API_KEY, JWT_TOKEN)
+# 10. Environment variable naming:
+#     - Use UPPER_SNAKE_CASE for credential keys
+#     - Add env_prefix for namespacing (APP_, SERVICE_, PROD_, etc.)
+#     - Avoid generic names like "KEY" or "TOKEN" (use API_KEY, JWT_TOKEN)
+#     - Global env_prefix applies to all projects, can override per-project
+#
+# 11. Project slugs:
+#     - Use lowercase alphanumeric + hyphens/underscores
+#     - Pattern: service-environment (api-staging, worker-prod)
+#     - Or: service_version-env (api_v2-staging, backend_legacy-prod)
+#     - Examples: backend-api, frontend_app, worker-staging, my_service-v2
 #
-# 8. Compliance / FIPS mode:
-#    - Set allow_plain_secrets: false for compliance
-#    - Use GPG with FIPS 140-2 validated crypto if required
-#    - Document encryption method in security policy
+# 12. Compliance / FIPS mode:
+#     - Set allow_plain_secrets: false for compliance
+#     - Use GPG with FIPS 140-2 validated crypto if required
+#     - Document encryption method in security policy
+#     - Track rotation with metadata.expires and rotation.interval
 #
 # Schema Documentation:
 #   https://github.com/fulmenhq/crucible/blob/main/docs/standards/devsecops/project-secrets.md

package/config/crucible-ts/taxonomy/metrics.yaml

@@ -44,6 +44,11 @@ $defs:
       - fulhash_hash_string_total
       - fulhash_bytes_hashed_total
       - fulhash_operation_ms
+      - http_requests_total
+      - http_request_duration_seconds
+      - http_request_size_bytes
+      - http_response_size_bytes
+      - http_active_requests
   metricUnit:
     type: string
     enum:
@@ -70,6 +75,16 @@ properties:
             description: Default millisecond buckets used when metric name ends with `_ms`.
             items:
               type: number
+          seconds_metrics:
+            type: array
+            description: Default second buckets used when metric unit is `s` (for HTTP latency and duration metrics).
+            items:
+              type: number
+          bytes_metrics:
+            type: array
+            description: Default byte buckets used when metric name ends with `_bytes` (for HTTP request/response size metrics).
+            items:
+              type: number
         additionalProperties: false
     additionalProperties: false
   metrics:
@@ -93,7 +108,7 @@ required:
   - version
   - metrics
 additionalProperties: false
-version: "0.2.15"
+version: "0.2.18"
 defaults:
   histogram_buckets:
     ms_metrics:
@@ -106,6 +121,25 @@ defaults:
       - 1000
       - 5000
       - 10000
+    seconds_metrics:
+      - 0.005
+      - 0.01
+      - 0.025
+      - 0.05
+      - 0.1
+      - 0.25
+      - 0.5
+      - 1
+      - 2.5
+      - 5
+      - 10
+    bytes_metrics:
+      - 1024
+      - 10240
+      - 102400
+      - 1048576
+      - 10485760
+      - 104857600
 metrics:
   - name: schema_validations
     unit: count
@@ -269,3 +303,28 @@ metrics:
     unit: ms
     description: >
       Hash operation latency in milliseconds for all algorithms. Uses ADR-0007 buckets: [1, 5, 10, 50, 100, 500, 1000, 5000, 10000]. Enables performance benchmarking across XXH3-128 and SHA256.
+
+  - name: http_requests_total
+    unit: count
+    description: >
+      Total HTTP server requests received. Counter metric tracking all HTTP requests by method, route, status, and service. Required labels: method (GET/POST/etc), route (templated path like /users/:id to avoid cardinality), status (HTTP status code), service (service identifier). Optional labels: outcome (2xx/4xx/5xx grouping derived from status). IMPORTANT: Use normalized/templated routes (e.g., /users/:id, not /users/123) to prevent cardinality explosion. Helpers SHOULD provide route normalization utilities.
+
+  - name: http_request_duration_seconds
+    unit: s
+    description: >
+      HTTP server request duration in seconds. Histogram metric measuring request latency from receipt to response. Uses default seconds buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]. Required labels: method, route (templated), status, service. Optional labels: outcome. Helpers exposing millisecond APIs MUST document unit conversion (1 second = 1000 ms). Use templated routes to control cardinality.
+
+  - name: http_request_size_bytes
+    unit: bytes
+    description: >
+      HTTP server request body size in bytes. Histogram metric measuring incoming request payload sizes. Uses default bytes buckets: [1024, 10240, 102400, 1048576, 10485760, 104857600] (1KB to 100MB). Required labels: method, route (templated), service. Enables monitoring payload patterns and capacity planning. Use templated routes to avoid cardinality issues.
+
+  - name: http_response_size_bytes
+    unit: bytes
+    description: >
+      HTTP server response body size in bytes. Histogram metric measuring outgoing response payload sizes. Uses default bytes buckets: [1024, 10240, 102400, 1048576, 10485760, 104857600] (1KB to 100MB). Required labels: method, route (templated), status, service. Optional labels: outcome. Tracks bandwidth usage and response patterns. Use templated routes to prevent cardinality explosion.
+
+  - name: http_active_requests
+    unit: count
+    description: >
+      Number of HTTP requests currently being processed. Gauge metric tracking concurrent request load. Required labels: service. Intentionally minimal labels to avoid cardinality. Helps monitor server capacity and saturation. Increment on request start, decrement on completion.