@aicgen/aicgen 1.0.0-beta.1 → 1.0.0-beta.2

package/data/devops/observability.md

@@ -1,73 +1,73 @@
-# Observability
-
-## Overview
-
-Observability is the ability to understand the internal state of a system by examining its outputs. In modern distributed systems, it goes beyond simple monitoring to include logging, metrics, and tracing.
-
-## Three Pillars
-
-### 1. Structured Logging
-
-Logs should be machine-readable (JSON) and contain context.
-
-```json
-// ✅ Good: Structured JSON logging
-{
-  "level": "info",
-  "message": "Order processed",
-  "orderId": "ord_123",
-  "userId": "user_456",
-  "amount": 99.99,
-  "durationMs": 145,
-  "status": "success"
-}
-```
-```text
-// ❌ Bad: Unstructured text
-"Order processed: ord_123 for user_456"
-```
-
-### 2. Metrics
-
-Aggregatable data points for identifying trends and health.
-
-- **Counters**: Total requests, error counts (`http_requests_total`)
-- **Gauges**: Queue depth, memory usage (`memory_usage_bytes`)
-- **Histograms**: Request latency distribution (`http_request_duration_seconds`)
-
-### 3. Distributed Tracing
-
-Tracking requests as they propagate through services.
-
-- **Trace ID**: Unique ID for the entire request chain
-- **Span ID**: Unique ID for a specific operation
-- **Context Propagation**: Passing IDs between services (e.g., W3C Trace Context)
-
-## Implementation Strategy
-
-### OpenTelemetry (OTel)
-
-Use OpenTelemetry as the vendor-neutral standard for collecting telemetry data.
-
-```text
-# Initialize OpenTelemetry SDK
-SDK.Configure({
-  TraceExporter: Console/OTLP,
-  Instrumentations: [Http, Database, Grpc]
-})
-SDK.Start()
-```
-
-### Health Checks
-
-Expose standard health endpoints:
-
-- `/health/live`: Is the process running? (Liveness)
-- `/health/ready`: Can it accept traffic? (Readiness)
-- `/health/startup`: Has it finished initializing? (Startup)
-
-## Alerting Best Practices
-
-- **Alert on Symptoms, not Causes**: "High Error Rate" (Symptom) vs "CPU High" (Cause).
-- **Golden Signals**: Latency, Traffic, Errors, Saturation.
-- **Actionable**: Every alert should require a specific human action.
+# Observability
+
+## Overview
+
+Observability is the ability to understand the internal state of a system by examining its outputs. In modern distributed systems, it goes beyond simple monitoring to include logging, metrics, and tracing.
+
+## Three Pillars
+
+### 1. Structured Logging
+
+Logs should be machine-readable (JSON) and contain context.
+
+```json
+// ✅ Good: Structured JSON logging
+{
+  "level": "info",
+  "message": "Order processed",
+  "orderId": "ord_123",
+  "userId": "user_456",
+  "amount": 99.99,
+  "durationMs": 145,
+  "status": "success"
+}
+```
+```text
+// ❌ Bad: Unstructured text
+"Order processed: ord_123 for user_456"
+```
+
+### 2. Metrics
+
+Aggregatable data points for identifying trends and health.
+
+- **Counters**: Total requests, error counts (`http_requests_total`)
+- **Gauges**: Queue depth, memory usage (`memory_usage_bytes`)
+- **Histograms**: Request latency distribution (`http_request_duration_seconds`)
+
+### 3. Distributed Tracing
+
+Tracking requests as they propagate through services.
+
+- **Trace ID**: Unique ID for the entire request chain
+- **Span ID**: Unique ID for a specific operation
+- **Context Propagation**: Passing IDs between services (e.g., W3C Trace Context)
+
+## Implementation Strategy
+
+### OpenTelemetry (OTel)
+
+Use OpenTelemetry as the vendor-neutral standard for collecting telemetry data.
+
+```text
+# Initialize OpenTelemetry SDK
+SDK.Configure({
+  TraceExporter: Console/OTLP,
+  Instrumentations: [Http, Database, Grpc]
+})
+SDK.Start()
+```
+
+### Health Checks
+
+Expose standard health endpoints:
+
+- `/health/live`: Is the process running? (Liveness)
+- `/health/ready`: Can it accept traffic? (Readiness)
+- `/health/startup`: Has it finished initializing? (Startup)
+
+## Alerting Best Practices
+
+- **Alert on Symptoms, not Causes**: "High Error Rate" (Symptom) vs "CPU High" (Cause).
+- **Golden Signals**: Latency, Traffic, Errors, Saturation.
+- **Actionable**: Every alert should require a specific human action.