universal-dev-standards 4.2.0 → 5.0.0-beta.10

package/bundled/core/logging-standards.md

@@ -2,9 +2,12 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/logging-standards.md)
 
-**Version**: 1.1.0
-**Last Updated**: 2026-01-05
+**Version**: 1.2.0
+**Last Updated**: 2026-01-24
 **Applicability**: All software projects
+**Scope**: universal
+**Industry Standards**: RFC 5424, OpenTelemetry, W3C Trace Context
+**References**: [opentelemetry.io](https://opentelemetry.io/)
 
 ---
 
@@ -221,6 +224,334 @@ For microservices, include:
 - `span_id`: ID for this specific operation
 - `parent_span_id`: ID of the calling operation
 
+---
+
+## OpenTelemetry Integration
+
+### Semantic Conventions
+
+OpenTelemetry defines standardized attribute names for consistent observability. Follow these conventions for cross-tool interoperability.
+
+**Resource Attributes** (service identity):
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `service.name` | Logical service name | `payment-service` |
+| `service.version` | Service version | `2.3.1` |
+| `service.instance.id` | Unique instance identifier | `pod-abc123` |
+| `deployment.environment` | Environment name | `production` |
+
+**HTTP Attributes**:
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `http.request.method` | HTTP method | `POST` |
+| `http.route` | Route pattern | `/api/v1/users/{id}` |
+| `http.response.status_code` | Response status | `200` |
+| `url.path` | Request path | `/api/v1/users/123` |
+| `server.address` | Server hostname | `api.example.com` |
+
+**Database Attributes**:
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `db.system` | Database type | `postgresql` |
+| `db.name` | Database name | `orders_db` |
+| `db.operation` | Operation type | `SELECT` |
+| `db.statement` | Sanitized query | `SELECT * FROM users WHERE id = ?` |
+
+**Example Structured Log with OTel Conventions**:
+
+```json
+{
+  "timestamp": "2026-01-15T10:30:00.123Z",
+  "severity": "INFO",
+  "body": "Order created successfully",
+  "resource": {
+    "service.name": "order-service",
+    "service.version": "1.5.0",
+    "deployment.environment": "production"
+  },
+  "attributes": {
+    "trace_id": "abc123def456",
+    "span_id": "span789",
+    "http.request.method": "POST",
+    "http.route": "/api/v1/orders",
+    "http.response.status_code": 201,
+    "order.id": "ORD-12345",
+    "user.id": "usr-67890"
+  }
+}
+```
+
+### Log Severity Mapping
+
+Map traditional log levels to OpenTelemetry severity:
+
+| Traditional | OTel Severity | OTel Number |
+|-------------|---------------|-------------|
+| TRACE | TRACE | 1-4 |
+| DEBUG | DEBUG | 5-8 |
+| INFO | INFO | 9-12 |
+| WARN | WARN | 13-16 |
+| ERROR | ERROR | 17-20 |
+| FATAL | FATAL | 21-24 |
+
+---
+
+## Observability Three Pillars Integration
+
+### Logs, Metrics, and Traces Correlation
+
+Modern observability requires correlating the three pillars through shared identifiers.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Observability Three Pillars                   │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│   ┌──────────┐    trace_id    ┌──────────┐    trace_id    ┌──────────┐
+│   │  LOGS    │◄──────────────►│  TRACES  │◄──────────────►│ METRICS  │
+│   │ (Events) │                │ (Spans)  │                │(Counters)│
+│   └──────────┘                └──────────┘                └──────────┘
+│        │                           │                           │
+│        │     Correlation Keys      │                           │
+│        │  ┌─────────────────────┐ │                           │
+│        └──┤ trace_id, span_id,  ├──┘                           │
+│           │ service.name        │──────────────────────────────┘
+│           └─────────────────────┘
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Implementation Pattern
+
+**Step 1: Extract Context from Incoming Requests**
+
+```javascript
+// Middleware extracts trace context from headers
+app.use((req, res, next) => {
+  const traceId = req.headers['traceparent']?.split('-')[1] || generateTraceId();
+  const spanId = generateSpanId();
+
+  req.traceContext = { traceId, spanId };
+
+  // Store in async local storage for automatic propagation
+  asyncLocalStorage.run({ traceId, spanId }, () => next());
+});
+```
+
+**Step 2: Emit Correlated Logs**
+
+```javascript
+logger.info('Processing order', {
+  trace_id: context.traceId,
+  span_id: context.spanId,
+  order_id: orderId
+});
+```
+
+**Step 3: Record Metrics with Exemplars**
+
+```javascript
+// Exemplars link metrics to specific traces
+orderCounter.add(1, {
+  'status': 'success'
+}, {
+  traceId: context.traceId,
+  spanId: context.spanId
+});
+```
+
+**Step 4: Query Across Pillars**
+
+```
+// In Grafana: Jump from metric spike to related traces
+// In Jaeger: View logs associated with a trace
+// In Loki: Find traces for specific log patterns
+```
+
+### Correlation Best Practices
+
+| Practice | Benefit |
+|----------|---------|
+| Always include `trace_id` in logs | Jump from log to full trace |
+| Add `trace_id` as metric exemplar | Investigate metric anomalies |
+| Use consistent `service.name` | Filter across all pillars |
+| Propagate context across async boundaries | Maintain correlation in async ops |
+
+---
+
+## Log-based Alerting
+
+### Alert Design Principles
+
+**1. Avoid Alert Storms**
+
+```yaml
+# Bad: Alert on every error
+- alert: ErrorOccurred
+  expr: log_errors_total > 0  # ❌ Too noisy
+
+# Good: Alert on error rate increase
+- alert: ErrorRateHigh
+  expr: rate(log_errors_total[5m]) > 0.01  # ✅ Rate-based
+  for: 5m
+  annotations:
+    summary: "Error rate exceeds 1% over 5 minutes"
+```
+
+**2. Group Related Alerts**
+
+```yaml
+# Group by service and error type
+group_by: ['service', 'error_type']
+group_wait: 30s
+group_interval: 5m
+```
+
+**3. Include Actionable Context**
+
+```yaml
+annotations:
+  summary: "{{ $labels.service }} error rate high"
+  description: "Error rate {{ $value | printf \"%.2f\" }}% in last 5m"
+  runbook_url: "https://wiki.example.com/runbooks/error-rate-high"
+  dashboard_url: "https://grafana.example.com/d/service-errors"
+```
+
+### Alert Severity Guidelines
+
+| Severity | Response Time | Example Conditions |
+|----------|---------------|-------------------|
+| Critical | Immediate (page) | Service down, data loss risk |
+| Warning | Within hours | Error rate elevated, resource 80% |
+| Info | Next business day | Deprecation warnings, minor anomalies |
+
+### Log-based Alert Patterns
+
+**Pattern 1: Error Rate Threshold**
+
+```promql
+# Alert when error rate exceeds threshold
+sum(rate(log_messages_total{level="error"}[5m])) by (service)
+/
+sum(rate(log_messages_total[5m])) by (service) > 0.05
+```
+
+**Pattern 2: Absence of Expected Logs**
+
+```promql
+# Alert when heartbeat logs missing
+absent(log_messages_total{message=~".*heartbeat.*"}[5m])
+```
+
+**Pattern 3: Specific Error Patterns**
+
+```promql
+# Alert on specific error codes
+sum(rate(log_messages_total{error_code=~"DB_.*"}[5m])) > 10
+```
+
+### De-duplication Strategies
+
+| Strategy | Implementation | Use Case |
+|----------|----------------|----------|
+| Time-based | Ignore same alert within N minutes | Flapping alerts |
+| Fingerprint | Hash of alert labels | Identical alerts |
+| Dependency | Suppress child alerts when parent fires | Cascading failures |
+
+---
+
+## Advanced Correlation Patterns
+
+### Cross-Service Correlation ID
+
+Propagate correlation context across service boundaries:
+
+**HTTP Header Propagation**:
+
+```
+┌───────────────┐         ┌───────────────┐         ┌───────────────┐
+│  Service A    │────────►│  Service B    │────────►│  Service C    │
+│               │         │               │         │               │
+│ trace_id: abc │         │ trace_id: abc │         │ trace_id: abc │
+│ span_id: 001  │         │ span_id: 002  │         │ span_id: 003  │
+│               │         │ parent: 001   │         │ parent: 002   │
+└───────────────┘         └───────────────┘         └───────────────┘
+        │                         │                         │
+        ▼                         ▼                         ▼
+   ┌─────────────────────────────────────────────────────────────┐
+   │                  Centralized Log Storage                     │
+   │  Query: trace_id="abc" → Returns logs from all 3 services   │
+   └─────────────────────────────────────────────────────────────┘
+```
+
+**W3C Trace Context Headers**:
+
+```http
+traceparent: 00-abc123def456-span789-01
+tracestate: vendor=value
+```
+
+**Message Queue Propagation**:
+
+```json
+{
+  "headers": {
+    "traceparent": "00-abc123-def456-01"
+  },
+  "body": {
+    "order_id": "ORD-123",
+    "action": "process"
+  }
+}
+```
+
+### Async Operation Correlation
+
+For background jobs and async operations:
+
+```javascript
+// When enqueueing job
+const job = {
+  data: { orderId: 123 },
+  metadata: {
+    trace_id: currentContext.traceId,
+    correlation_id: generateCorrelationId(),
+    enqueued_at: new Date().toISOString()
+  }
+};
+
+// When processing job
+logger.info('Processing background job', {
+  trace_id: job.metadata.trace_id,
+  correlation_id: job.metadata.correlation_id,
+  job_type: 'order_processing',
+  queue_time_ms: Date.now() - new Date(job.metadata.enqueued_at)
+});
+```
+
+### Business Transaction Correlation
+
+For multi-step business processes:
+
+```json
+{
+  "timestamp": "2026-01-15T10:30:00.123Z",
+  "level": "INFO",
+  "message": "Order payment completed",
+  "trace_id": "abc123",
+  "business_correlation": {
+    "transaction_id": "TXN-789",
+    "order_id": "ORD-456",
+    "customer_id": "CUST-123",
+    "flow_step": "3/5",
+    "flow_name": "order_fulfillment"
+  }
+}
+```
+
 ## Performance Considerations
 
 ### Log Volume Management
@@ -304,6 +635,7 @@ App cannot continue?         → FATAL
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.2.0 | 2026-01-24 | Added: OpenTelemetry Semantic Conventions, Observability Three Pillars Integration, Log-based Alerting, Advanced Correlation Patterns |
 | 1.1.0 | 2026-01-05 | Added: References section with OWASP, RFC 5424, OpenTelemetry, and 12 Factor App |
 | 1.0.0 | 2025-12-30 | Initial logging standards |
 
@@ -314,7 +646,10 @@ App cannot continue?         → FATAL
 - [OWASP Logging Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html) - Security logging best practices
 - [RFC 5424 - The Syslog Protocol](https://datatracker.ietf.org/doc/html/rfc5424) - Standard log message format
 - [OpenTelemetry Logging](https://opentelemetry.io/docs/specs/otel/logs/) - Modern observability standard
+- [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/) - Standardized attribute naming
+- [W3C Trace Context](https://www.w3.org/TR/trace-context/) - Distributed tracing context propagation
 - [12 Factor App - Logs](https://12factor.net/logs) - Cloud-native logging principles
+- [Google SRE - Alerting on SLOs](https://sre.google/workbook/alerting-on-slos/) - Alert design best practices
 
 ---
 

package/bundled/core/performance-standards.md

@@ -0,0 +1,231 @@
+# Performance Standards
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/performance-standards.md)
+
+**Version**: 1.1.0
+**Last Updated**: 2026-01-29
+**Applicability**: All software projects
+**Scope**: universal
+**Industry Standards**: ISO/IEC 25010 Performance Efficiency
+**References**: [sre.google](https://sre.google/books/)
+
+> **For detailed explanations and optimization techniques, see [Performance Guide](guides/performance-guide.md)**
+
+---
+
+## Purpose
+
+This standard defines comprehensive guidelines for software performance engineering, covering performance requirements, testing methodologies, and monitoring practices.
+
+**Reference Standards**:
+- [ISO/IEC 25010:2011](https://www.iso.org/standard/35733.html) - Performance Efficiency
+- [Google SRE Book](https://sre.google/books/) - Site Reliability Engineering
+
+---
+
+## Performance Requirements Template
+
+### NFR Format
+
+```markdown
+### NFR-PERF-XXX: [Title]
+
+**Category**: Performance Efficiency > [Time Behavior/Resource Utilization/Capacity]
+**Priority**: P1/P2/P3
+
+**Requirement**:
+| Percentile | Target | Maximum |
+|------------|--------|---------|
+| p50 | Xms | Yms |
+| p95 | Xms | Yms |
+| p99 | Xms | Yms |
+
+**Conditions**: [Load, data volume, etc.]
+**Measurement**: [Tool, sampling, reporting]
+```
+
+---
+
+## Common Performance Targets
+
+| System Type | Response Time (p95) | Throughput | Availability |
+|-------------|---------------------|------------|--------------|
+| **E-commerce** | < 200ms | 1000+ rps | 99.9% |
+| **Internal Tools** | < 500ms | 100+ rps | 99.5% |
+| **Batch Processing** | N/A | 10K+ records/min | 99% |
+| **Real-time Systems** | < 50ms (p99) | 10K+ rps | 99.99% |
+| **API Gateway** | < 100ms | 5K+ rps | 99.95% |
+
+---
+
+## Core Web Vitals Targets
+
+| Metric | Target | Description |
+|--------|--------|-------------|
+| **LCP** (Largest Contentful Paint) | < 2.5s | Perceived load speed |
+| **INP** (Interaction to Next Paint) | < 200ms | Responsiveness |
+| **CLS** (Cumulative Layout Shift) | < 0.1 | Visual stability |
+
+---
+
+## Performance Budget
+
+```yaml
+# Example Performance Budget
+resources:
+  total_size: 500KB
+  javascript: 200KB
+  css: 50KB
+  images: 200KB
+  fonts: 50KB
+
+metrics:
+  time_to_interactive: 3s
+  first_contentful_paint: 1.5s
+  speed_index: 3s
+
+lighthouse_scores:
+  performance: 90
+  accessibility: 100
+  best_practices: 100
+  seo: 100
+```
+
+---
+
+## Performance Metrics
+
+### Percentile Guidelines
+
+| Percentile | Meaning | Use For |
+|------------|---------|---------|
+| **p50** | Median | Typical user experience |
+| **p90** | 90% faster | Most user experience |
+| **p95** | 95% faster | SLA threshold (common) |
+| **p99** | 99% faster | Worst case for most users |
+| **p99.9** | 99.9% faster | High-volume systems |
+
+### The Four Golden Signals (SRE)
+
+| Signal | What to Measure | Target |
+|--------|-----------------|--------|
+| **Latency** | Response time (p50, p95, p99) | < SLA |
+| **Traffic** | Requests per second | Depends on capacity |
+| **Errors** | Error rate % | < 0.1% |
+| **Saturation** | Resource utilization | < 70% sustained |
+
+---
+
+## Alerting Thresholds
+
+| Metric | Warning | Critical | Action |
+|--------|---------|----------|--------|
+| **p95 Response Time** | > 200ms | > 500ms | Investigate, scale |
+| **Error Rate** | > 0.1% | > 1% | Page on-call |
+| **CPU Usage** | > 70% | > 90% | Scale, optimize |
+| **Memory Usage** | > 80% | > 95% | Scale, investigate leak |
+| **Disk Usage** | > 80% | > 95% | Cleanup, expand |
+
+---
+
+## Capacity Planning Thresholds
+
+| Resource | Plan At | Critical |
+|----------|---------|----------|
+| **Compute (CPU)** | 70% sustained | 90% |
+| **Memory** | 80% | 95% |
+| **Storage** | 70% | 90% |
+| **Network** | 60% | 80% |
+| **Database Connections** | 80% | 95% |
+
+---
+
+## Connection Pooling Configuration
+
+| Parameter | Recommended | Notes |
+|-----------|-------------|-------|
+| **Min connections** | 5-10 | Keep warm connections |
+| **Max connections** | 20-100 | Depends on DB and app servers |
+| **Idle timeout** | 10-30 min | Release unused connections |
+| **Connection timeout** | 5-10 sec | Fail fast on issues |
+
+---
+
+## Rate Limiting Configuration
+
+| Endpoint Type | Limit | Burst |
+|---------------|-------|-------|
+| **Public API** | 100/min | 10 |
+| **Authenticated** | 1000/min | 50 |
+| **Premium tier** | 10000/min | 200 |
+| **Internal** | Unlimited | N/A |
+
+---
+
+## Performance Testing Frequency
+
+| Test Type | Development | Staging | Production |
+|-----------|-------------|---------|------------|
+| **Unit Performance** | Every commit | - | - |
+| **Load Testing** | Weekly | Every release | Monthly |
+| **Stress Testing** | Monthly | Every release | Quarterly |
+| **Soak Testing** | Monthly | Major releases | Quarterly |
+| **Spike Testing** | - | Major releases | Before events |
+
+---
+
+## Performance Checklists
+
+### Development Phase
+
+- [ ] Performance requirements defined and documented
+- [ ] Performance budget established
+- [ ] Database queries optimized (indexes, EXPLAIN)
+- [ ] Caching strategy implemented
+- [ ] Pagination for list endpoints
+- [ ] Async processing for long operations
+- [ ] Connection pooling configured
+
+### Pre-Release
+
+- [ ] Load testing completed with production-like data
+- [ ] Stress testing completed (found breaking point)
+- [ ] Performance regression tests in CI/CD
+- [ ] Core Web Vitals targets met (if frontend)
+- [ ] Database query analysis completed
+- [ ] Cache hit rates acceptable
+- [ ] Error rates under threshold
+
+### Production
+
+- [ ] APM monitoring configured
+- [ ] Performance dashboards created
+- [ ] Alerting thresholds defined
+- [ ] Capacity planning documented
+- [ ] Runbook for performance issues
+- [ ] Regular performance reviews scheduled
+
+---
+
+## Related Standards
+
+- [Testing Standards](testing-standards.md) - Performance testing integration
+- [Requirement Engineering](requirement-engineering.md) - NFR documentation
+- [Logging Standards](logging-standards.md) - Performance logging
+- [Code Review Checklist](code-review-checklist.md) - Performance review
+- [Deployment Standards](deployment-standards.md) - Performance validation pre-deployment
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.1.0 | 2026-01-29 | Refactored: Split into Rules + Guide, moved explanations to guide |
+| 1.0.0 | 2026-01-29 | Initial release |
+
+---
+
+## License
+
+This standard is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).