code-abyss 1.5.1

package/skills/devops/observability.md

@@ -0,0 +1,280 @@
+---
+name: observability
+description: 可观测性秘典。日志、指标、追踪三大支柱，告警设计，SLI/SLO/SLA。当用户提到可观测性、日志、监控、指标、追踪、告警、SLO时路由到此。
+---
+
+# 🔧 炼器秘典 · 可观测性
+
+
+## 三大支柱
+
+```
+┌─────────────────────────────────────────┐
+│            可观测性 (Observability)       │
+├─────────────┬─────────────┬─────────────┤
+│   📋 日志   │   📊 指标   │   🔗 追踪   │
+│   Logs      │   Metrics   │   Traces    │
+│  离散事件   │  聚合数值   │  请求链路   │
+│  What       │  How much   │  Where      │
+└─────────────┴─────────────┴─────────────┘
+```
+
+| 支柱 | 特征 | 适用场景 | 代表工具 |
+|------|------|----------|----------|
+| 日志 | 离散、非结构化/结构化事件 | 调试、审计、错误追踪 | ELK, Loki, CloudWatch |
+| 指标 | 聚合数值、时间序列 | 告警、趋势、容量规划 | Prometheus, Datadog, CloudWatch |
+| 追踪 | 分布式请求链路 | 延迟分析、依赖映射 | Jaeger, Zipkin, X-Ray |
+
+---
+
+## 日志 (Logs)
+
+### 结构化日志
+
+```json
+{
+  "timestamp": "2024-01-15T10:30:00.123Z",
+  "level": "ERROR",
+  "service": "order-service",
+  "trace_id": "abc123",
+  "span_id": "def456",
+  "message": "Payment failed",
+  "error": "InsufficientFunds",
+  "user_id": "u-789",
+  "order_id": "o-012",
+  "amount": 99.99,
+  "duration_ms": 234
+}
+```
+
+### 日志级别规范
+
+| 级别 | 用途 | 生产环境 |
+|------|------|----------|
+| TRACE | 极细粒度调试 | ❌ 关闭 |
+| DEBUG | 开发调试信息 | ❌ 关闭 |
+| INFO | 业务关键事件 | ✅ 开启 |
+| WARN | 潜在问题，可自愈 | ✅ 开启 |
+| ERROR | 错误，需关注 | ✅ 开启 + 告警 |
+| FATAL | 致命错误，服务不可用 | ✅ 开启 + 紧急告警 |
+
+### 日志聚合架构
+
+```
+应用 → Filebeat/Fluentd → Kafka(缓冲) → Logstash → Elasticsearch → Kibana
+                                       → S3(归档)
+```
+
+### 日志最佳实践
+
+- ✅ 结构化 JSON 格式
+- ✅ 包含 trace_id 关联追踪
+- ✅ 敏感数据脱敏
+- ✅ 合理的保留策略（热/温/冷）
+- ❌ 不记录密码/Token
+- ❌ 不在循环中打日志
+- ❌ 不用字符串拼接（用参数化）
+
+---
+
+## 指标 (Metrics)
+
+### Prometheus 指标类型
+
+| 类型 | 用途 | 示例 |
+|------|------|------|
+| Counter | 只增不减的计数器 | 请求总数、错误总数 |
+| Gauge | 可增可减的瞬时值 | 当前连接数、队列长度 |
+| Histogram | 分布统计（桶） | 请求延迟分布 |
+| Summary | 分布统计（分位数） | 请求延迟 P99 |
+
+### 关键 PromQL
+
+```promql
+# 请求速率
+rate(http_requests_total[5m])
+
+# 错误率
+rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m])
+
+# P99 延迟
+histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))
+
+# CPU 使用率
+1 - avg(rate(node_cpu_seconds_total{mode="idle"}[5m])) by (instance)
+
+# 内存使用率
+(node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes) / node_memory_MemTotal_bytes
+```
+
+### Grafana Dashboard 设计
+
+```yaml
+四大黄金信号 Dashboard:
+  Row 1 - 流量:
+    - QPS (rate)
+    - 按 endpoint 分组
+  Row 2 - 错误:
+    - 错误率 (%)
+    - 按错误类型分组
+  Row 3 - 延迟:
+    - P50/P95/P99
+    - 延迟热力图
+  Row 4 - 饱和度:
+    - CPU/Memory/Disk
+    - 连接池使用率
+```
+
+---
+
+## 追踪 (Traces)
+
+### OpenTelemetry 集成
+
+```python
+# Python 示例
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+
+provider = TracerProvider()
+processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="http://collector:4317"))
+provider.add_span_processor(processor)
+trace.set_tracer_provider(provider)
+
+tracer = trace.get_tracer(__name__)
+
+@tracer.start_as_current_span("process_order")
+def process_order(order_id: str):
+    span = trace.get_current_span()
+    span.set_attribute("order.id", order_id)
+    # 业务逻辑...
+```
+
+### 追踪架构
+
+```
+Service-A → Service-B → Service-C
+    │            │            │
+    └── Span ────┴── Span ────┴── Span
+         │
+    Trace (trace_id 贯穿全链路)
+```
+
+### Context Propagation
+
+```
+HTTP Header: traceparent: 00-{trace_id}-{span_id}-{flags}
+gRPC Metadata: 自动传播
+Message Queue: 消息头注入 trace context
+```
+
+---
+
+## 告警设计
+
+### 告警分级
+
+| 级别 | 响应时间 | 通知方式 | 示例 |
+|------|----------|----------|------|
+| P0 Critical | 立即 | 电话 + PagerDuty | 服务完全不可用 |
+| P1 High | 15 min | Slack + 短信 | 错误率 > 5% |
+| P2 Medium | 1 hour | Slack | 延迟 P99 > 阈值 |
+| P3 Low | 次日 | 邮件/工单 | 磁盘使用 > 70% |
+
+### 告警规则示例
+
+```yaml
+# Prometheus AlertManager
+groups:
+  - name: service-alerts
+    rules:
+      - alert: HighErrorRate
+        expr: rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m]) > 0.05
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: "High error rate on {{ $labels.instance }}"
+
+      - alert: HighLatency
+        expr: histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m])) > 1
+        for: 5m
+        labels:
+          severity: warning
+```
+
+### 告警最佳实践
+
+- ✅ 基于 SLO 告警，而非资源指标
+- ✅ 设置合理的 `for` 持续时间，避免抖动
+- ✅ 告警必须可操作（收到告警知道该做什么）
+- ✅ 定期审查告警，清理无效告警
+- ❌ 不对每个指标都告警（告警疲劳）
+- ❌ 不设过低阈值（噪音）
+
+---
+
+## SLI / SLO / SLA
+
+### 定义
+
+| 概念 | 含义 | 示例 |
+|------|------|------|
+| SLI (指标) | 服务质量的量化度量 | 请求成功率、P99 延迟 |
+| SLO (目标) | SLI 的目标值 | 可用性 99.9%、P99 < 200ms |
+| SLA (协议) | 对外承诺 + 违约后果 | 99.9% 可用，否则赔偿 |
+
+### Error Budget
+
+```
+SLO = 99.9% 可用性
+Error Budget = 1 - 0.999 = 0.1%
+每月 Error Budget = 30天 × 24小时 × 60分钟 × 0.001 = 43.2 分钟
+
+已消耗: 15 分钟
+剩余: 28.2 分钟
+```
+
+### SLO Dashboard
+
+```yaml
+SLO Dashboard:
+  - 当前 SLI 值 vs SLO 目标
+  - Error Budget 剩余百分比
+  - Error Budget 消耗速率
+  - 30天滚动窗口趋势
+  - Burn Rate 告警状态
+```
+
+---
+
+## 可观测性清单
+
+```yaml
+日志:
+  - [ ] 结构化 JSON 格式
+  - [ ] trace_id 关联
+  - [ ] 敏感数据脱敏
+  - [ ] 保留策略配置
+
+指标:
+  - [ ] 四大黄金信号覆盖
+  - [ ] 自定义业务指标
+  - [ ] Dashboard 就绪
+  - [ ] 告警规则配置
+
+追踪:
+  - [ ] OpenTelemetry 集成
+  - [ ] 跨服务 Context Propagation
+  - [ ] 采样策略配置
+  - [ ] 关键路径标注
+
+告警:
+  - [ ] 基于 SLO 的告警
+  - [ ] 分级通知渠道
+  - [ ] Runbook 关联
+  - [ ] 定期审查机制
+```
+

package/skills/devops/performance.md

@@ -0,0 +1,273 @@
+---
+name: performance
+description: 性能优化秘典。性能分析方法论、Profiling、火焰图、基准测试、瓶颈优化。当用户提到性能、延迟、吞吐、Profiling、火焰图、基准测试时路由到此。
+---
+
+# 🔧 炼器秘典 · 性能优化
+
+
+## 性能分析方法论
+
+### USE 方法 (Utilization, Saturation, Errors)
+
+对每个资源检查三个维度：
+
+| 维度 | 含义 | 工具 |
+|------|------|------|
+| Utilization | 资源繁忙时间占比 | `top`, `vmstat`, `iostat` |
+| Saturation | 排队等待的工作量 | `vmstat`(r列), `iostat`(avgqu-sz) |
+| Errors | 错误事件计数 | `dmesg`, 应用日志 |
+
+```bash
+# CPU USE
+mpstat -P ALL 1          # Utilization per core
+vmstat 1                 # Saturation (r > CPU count)
+dmesg | grep -i error    # Errors
+
+# Memory USE
+free -m                  # Utilization
+vmstat 1 | awk '{print $3,$4}'  # Saturation (si/so > 0 = swapping)
+
+# Disk USE
+iostat -xz 1             # Utilization (%util), Saturation (avgqu-sz)
+
+# Network USE
+sar -n DEV 1             # Utilization
+netstat -s | grep -i error  # Errors
+```
+
+### RED 方法 (Rate, Errors, Duration)
+
+面向服务的性能指标：
+
+| 维度 | 含义 | 示例 |
+|------|------|------|
+| Rate | 每秒请求数 | QPS/RPS |
+| Errors | 每秒错误数 | 5xx/s |
+| Duration | 请求延迟分布 | P50/P95/P99 |
+
+```promql
+# Prometheus PromQL 示例
+rate(http_requests_total[5m])                    # Rate
+rate(http_requests_total{status=~"5.."}[5m])     # Errors
+histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))  # P99
+```
+
+---
+
+## Profiling 工具
+
+### CPU Profiling
+
+| 语言 | 工具 | 命令 |
+|------|------|------|
+| Python | cProfile / py-spy | `py-spy record -o profile.svg -- python app.py` |
+| Go | pprof | `go tool pprof http://localhost:6060/debug/pprof/profile` |
+| Java | async-profiler | `./profiler.sh -d 30 -f flame.html <pid>` |
+| Node.js | clinic.js | `clinic flame -- node app.js` |
+| Rust | cargo-flamegraph | `cargo flamegraph` |
+| 系统级 | perf | `perf record -g -p <pid> -- sleep 30` |
+
+### Memory Profiling
+
+```bash
+# Python
+python -m memory_profiler script.py
+# 或使用 tracemalloc
+python -c "import tracemalloc; tracemalloc.start(); ..."
+
+# Go
+go tool pprof http://localhost:6060/debug/pprof/heap
+
+# Java
+jmap -dump:format=b,file=heap.hprof <pid>
+jhat heap.hprof  # 或用 MAT/VisualVM 分析
+
+# 系统级
+valgrind --tool=massif ./program
+```
+
+### I/O Profiling
+
+```bash
+# 磁盘 I/O
+iostat -xz 1
+iotop -oP
+strace -e trace=read,write -p <pid>
+
+# 网络 I/O
+ss -tnp                    # 连接状态
+tcpdump -i eth0 -w cap.pcap  # 抓包
+```
+
+---
+
+## 火焰图
+
+### 生成流程
+
+```bash
+# 1. 采集数据
+perf record -F 99 -g -p <pid> -- sleep 30
+
+# 2. 生成火焰图
+perf script | stackcollapse-perf.pl | flamegraph.pl > flame.svg
+
+# 3. 解读
+# X轴：函数在采样中出现的比例（越宽=越耗时）
+# Y轴：调用栈深度
+# 颜色：随机，无特殊含义
+```
+
+### 解读要点
+
+| 特征 | 含义 | 行动 |
+|------|------|------|
+| 宽平顶 | 该函数自身耗时大 | 优化该函数逻辑 |
+| 宽塔形 | 调用链深但每层都耗时 | 减少调用层级 |
+| 多个窄尖峰 | 多处小开销累积 | 关注热路径 |
+
+---
+
+## 基准测试
+
+### HTTP 基准测试
+
+```bash
+# wrk (推荐)
+wrk -t12 -c400 -d30s http://localhost:8080/api
+
+# ab (Apache Bench)
+ab -n 10000 -c 100 http://localhost:8080/api
+
+# hey
+hey -n 10000 -c 100 http://localhost:8080/api
+
+# k6 (脚本化)
+k6 run --vus 100 --duration 30s script.js
+```
+
+### 代码级基准测试
+
+```python
+# Python - pytest-benchmark
+def test_sort_benchmark(benchmark):
+    data = list(range(1000, 0, -1))
+    benchmark(sorted, data)
+
+# Go
+func BenchmarkSort(b *testing.B) {
+    for i := 0; i < b.N; i++ {
+        sort.Ints(generateData())
+    }
+}
+
+# Rust
+#[bench]
+fn bench_sort(b: &mut Bencher) {
+    b.iter(|| sort_data(test::black_box(generate_data())));
+}
+```
+
+### 基准测试原则
+
+1. **隔离环境** — 独占机器，关闭无关进程
+2. **预热** — 丢弃前 N 次结果
+3. **统计显著** — 多次运行取中位数
+4. **对比基线** — 优化前后对比，而非绝对值
+
+---
+
+## 常见瓶颈优化
+
+### CPU 密集型
+
+| 问题 | 优化 |
+|------|------|
+| 热循环 | 算法优化、减少分支 |
+| 序列化/反序列化 | 换用高效格式(protobuf/msgpack) |
+| 正则表达式 | 预编译、简化模式 |
+| 加密运算 | 硬件加速(AES-NI) |
+
+### I/O 密集型
+
+| 问题 | 优化 |
+|------|------|
+| 同步阻塞 I/O | 异步 I/O (asyncio/epoll) |
+| 频繁小文件读写 | 批量合并、缓冲区 |
+| 网络往返 | 连接池、批量请求、Pipeline |
+| DNS 解析 | 本地缓存 |
+
+### 内存相关
+
+| 问题 | 优化 |
+|------|------|
+| 内存泄漏 | Profiling 定位 + 修复引用 |
+| GC 压力 | 减少分配、对象池 |
+| 缓存未命中 | 数据局部性、紧凑布局 |
+| 大对象 | 流式处理、分片 |
+
+---
+
+## 数据库性能
+
+### 查询优化
+
+```sql
+-- 1. EXPLAIN 分析
+EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 123;
+
+-- 2. 索引优化
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+CREATE INDEX idx_orders_composite ON orders(user_id, created_at DESC);
+
+-- 3. 避免 N+1
+-- 差：循环查询
+-- 好：JOIN 或 IN 批量查询
+SELECT o.*, u.name FROM orders o JOIN users u ON o.user_id = u.id;
+
+-- 4. 分页优化
+-- 差：OFFSET 大数值
+SELECT * FROM orders ORDER BY id LIMIT 20 OFFSET 100000;
+-- 好：游标分页
+SELECT * FROM orders WHERE id > 100000 ORDER BY id LIMIT 20;
+```
+
+### 连接池配置
+
+```yaml
+# HikariCP (Java)
+maximumPoolSize: 10        # CPU核数 * 2 + 磁盘数
+minimumIdle: 5
+connectionTimeout: 30000
+idleTimeout: 600000
+
+# 通用公式
+pool_size = (core_count * 2) + effective_spindle_count
+```
+
+---
+
+## 性能优化清单
+
+```yaml
+应用层:
+  - [ ] 热路径 Profiling 完成
+  - [ ] 算法复杂度 ≤ O(n log n)
+  - [ ] 无 N+1 查询
+  - [ ] 连接池配置合理
+  - [ ] 异步 I/O 用于 I/O 密集操作
+
+数据库:
+  - [ ] 慢查询 < 100ms (P95)
+  - [ ] 索引覆盖高频查询
+  - [ ] 无全表扫描
+  - [ ] 连接池大小合理
+
+基础设施:
+  - [ ] CPU 利用率 < 70% (P95)
+  - [ ] 内存利用率 < 80%
+  - [ ] 磁盘 I/O 无饱和
+  - [ ] 网络无丢包
+```
+