monitoring-observability

监控与可观测性

基于 Prometheus、Grafana、OpenTelemetry 和 Langfuse 的封装，而不是重新讲解这些工具。本技能承载 OrchestKit 的增量内容（版本下限、团队决策、经验教训），其他内容均指向供应商文档。请从 references/ork-delta.md 开始。

上游已覆盖的内容（不要重述）

以下主题均由一手资料完整覆盖。请阅读原始资料，不要在本地重复编写。

主题	一手资料
Prometheus 指标类型、RED 方法、基数、PromQL	https://prometheus.io/docs/practices/
Alertmanager 分组、抑制、升级处理、运行手册	https://prometheus.io/docs/alerting/latest/configuration/
Grafana 仪表板、Loki 和 LogQL、Promtail	https://grafana.com/docs/
OpenTelemetry spans、采样、上下文传播	https://opentelemetry.io/docs/
Langfuse Python SDK（@observe、as_type、score_current_span、should_export_span、LangfuseMedia）	https://langfuse.com/docs/sdk/python
Langfuse v2 到 v4 的 Python 迁移路径，以及 v3 到 v5 的 JS 迁移路径	https://langfuse.com/docs/sdk/python/v4-migration
Langfuse 自托管（ClickHouse、Redis、S3、Helm）	https://langfuse.com/docs/deployment/self-host
Langfuse 成本跟踪、模型定价、Metrics API v2	https://langfuse.com/docs/model-usage-and-cost
Langfuse 分数、在线评估器、标注队列、提示词管理	https://langfuse.com/docs/scores/overview
Langfuse 框架集成（LangChain、LangGraph、CrewAI、Pydantic AI、Bedrock、LiveKit）	https://langfuse.com/docs/integrations
Agent 图、观测类型、渲染后的工具调用	https://langfuse.com/docs/tracing-features/agent-graphs
PSI、KS 检验、KL 和 JS 散度、Wasserstein、嵌入漂移	https://www.evidentlyai.com/blog/data-drift-detection-large-datasets
EWMA 控制图	https://www.itl.nist.gov/div898/handbook/pmc/section3/pmc324.htm
structlog、Winston、关联 ID、日志采样	https://www.structlog.org/en/stable/

快速参考

类别	规则	影响	适用场景
基础设施监控	1	CRITICAL	Grafana 仪表板、黄金信号、SLO/SLI
LLM 可观测性	1	HIGH	Langfuse 跟踪、观测类型、Agent 图
静默故障	3	HIGH	工具跳过、质量下降、循环/Token 激增告警

总计：3 个类别中的 5 条规则。 漂移检测、成本跟踪、评估打分、Prometheus 埋点和告警规则编写已移至上方列出的上游资料。

快速开始

# Langfuse v4 LLM tracing: semantic as_type plus inline scoring
from langfuse import observe, get_client

@observe(as_type="generation", name="analyze_content")
async def analyze_content(content: str):
    get_client().update_current_trace(
        user_id="user_123", session_id="session_abc",
        tags=["production", "orchestkit"],
    )
    result = await llm.generate(content)
    get_client().score_current_span(name="response_quality", value=0.85)
    return result

# Prometheus RED method, wired the way this repo expects (bounded labels only)
from prometheus_client import Counter, Histogram

http_requests = Counter('http_requests_total', 'Total requests', ['method', 'endpoint', 'status'])
http_duration = Histogram('http_request_duration_seconds', 'Request latency',
    buckets=[0.01, 0.05, 0.1, 0.5, 1, 2, 5])

基础设施监控

仪表板和健康检查模式。指标埋点和告警规则语法请参阅上游资料。

规则	文件	关键模式
Grafana 仪表板	rules/monitoring-grafana.md	黄金信号、SLO/SLI、健康检查

CC 2.1.161 — 将 OTEL 资源属性作为指标标签： 现在，OTEL_RESOURCE_ATTRIBUTES 的值会作为标签附加到指标数据点上，因此可以按自定义维度（团队、仓库、环境）筛选使用量指标。请为仪表板添加标签选择器，以便按租户/团队跟踪成本和用量。

LLM 可观测性

基于 Langfuse 为 LLM 应用提供跟踪。成本跟踪、评分和漂移统计已由上游覆盖；此处仅保留本仓库接入跟踪的方式。

规则	文件	关键模式
Langfuse 跟踪	rules/llm-langfuse-traces.md	@observe 装饰器、OTEL spans、Agent 图

静默故障

检测并告警 LLM Agent 中的静默故障。

规则	文件	关键模式
工具跳过	rules/silent-tool-skipping.md	预期与实际工具调用、Langfuse traces
质量下降	rules/silent-degraded-quality.md	启发式方法 + LLM-as-judge、z-score 基线
静默告警	rules/silent-alerting.md	循环检测、token 激增、升级工作流

CC 2.1.169 — OTEL 客户端证书路径需要信任确认： 不受信任的项目设置无法再在未经信任确认的情况下设置 OTEL 客户端证书路径。如果你的 OTEL exporter 使用在项目 .claude/settings.json 中配置的客户端证书，那么首次在不受信任的项目中使用时，会出现一次性信任提示 — 2.1.169 之后遥测数据静默中断，通常是因为这道关卡，而非 collector。

关键决策

决策	建议	理由
指标方法	RED 方法（速率、错误、耗时）	行业标准，涵盖服务健康状况的关键方面
日志格式	结构化 JSON	可由机器解析，支持日志聚合
追踪	OpenTelemetry	与供应商无关，支持自动插桩，生态系统广泛
LLM 可观测性	Langfuse（而非 LangSmith）	开源、可自托管，内置提示词管理
LLM 追踪 API	@observe(as_type=...) + score_current_span()	v4：语义类型、内联评分、span 筛选
Langfuse API	Observations API v2 + Metrics API v2	v4（2026 年 3 月）：查询更快，可大规模聚合
Hook 遥测传输	位于 ~/.claude/analytics/ 下的 JSONL，绝不在进程内使用 SDK	Hook 是按事件运行的进程；初始化 SDK 会在每次生成时产生开销（references/ork-delta.md）

详细文档

资源	描述
references/ork-delta.md	从这里开始。 上游文档未涵盖的基础要求、项目决策和经验教训
references/langfuse-js-v5.md	JS/TS SDK v5 相较于 Python 4.x 的差异：包映射、虚构包、SpanProcessor 与 exporter。编写任何 JS Langfuse 代码前请先阅读
references/experiments-api.md	本仓库使用的 Langfuse 实验和数据集运行
references/evaluation-scores.md	评分结构和评分流水线接线方式
references/session-tracking.md	多步骤工作流中的会话和用户分组
references/metrics-collection.md	Claude Code OTEL 指标清单和 collector 端关联
references/dashboards.md	仪表板布局规范
references/structured-logging.md	结构化日志字段规范
references/dev-agent-lens.md	用于 API 边界可观测性的 LiteLLM 代理层
examples/orchestkit-monitoring-dashboard.md	监控仪表板示例
scripts/	模板：Prometheus、OpenTelemetry、健康检查、Langfuse

相关技能

• defense-in-depth - 将第 8 层可观测性纳入安全架构
• devops-deployment - 将可观测性集成到 CI/CD 和 Kubernetes 中
• resilience-patterns - 监控熔断器和故障场景
• llm-evaluation - 与 Langfuse 评分集成的评估模式
• caching - 降低 Langfuse 所追踪成本的缓存策略