Back to Details

observability-advisor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Observability Advisor

可观测性顾问

Design and review telemetry that helps teams detect, diagnose, and improve service behavior before and during reliability problems.
Scope: Vendor-neutral observability architecture, signal design, coverage reviews, SLOs, alerting, and instrumentation plans. NOT for live incident coordination (incident-response-engineer), deep runtime bottleneck profiling (performance-profiler), or CloudWatch-specific implementation details (cloudwatch).
设计和评审遥测系统，帮助团队在可靠性问题发生前及发生期间检测、诊断并改进服务行为。
范围： 厂商中立的可观测性架构、信号设计、覆盖范围评审、SLO、告警及 instrumentation 规划。不适用于实时事件协调（请使用incident-response-engineer）、深度运行时瓶颈剖析（请使用performance-profiler）或CloudWatch特定实现细节（请使用cloudwatch）。

Canonical Vocabulary

标准术语表

TermDefinition
telemetryLogs, metrics, traces, profiles, and events emitted by a system
signalA measurable indicator used to detect or explain behavior
metricNumeric time-series measurement aggregated over time
logStructured event record capturing context for a specific occurrence
traceEnd-to-end record of work moving through distributed components
spanA timed unit of work within a trace
SLIConcrete measurement of a user-relevant reliability property
SLOTarget threshold and window for an SLI
error budgetAllowed unreliability implied by an SLO over its window
cardinalityNumber of unique label or attribute values attached to telemetry
术语定义
telemetry系统生成的日志、指标、链路追踪、性能剖析及事件
signal用于检测或解释系统行为的可测量指标
metric随时间聚合的数值型时间序列测量数据
log捕获特定事件上下文的结构化事件记录
trace跨分布式组件的端到端工作记录
spantrace中的一个计时工作单元
SLI用户相关可靠性属性的具体测量指标
SLOSLI的目标阈值及时间窗口
error budgetSLO在其时间窗口内允许的不可靠性范围
cardinality附加到遥测数据的唯一标签或属性值的数量

Dispatch

调度模式

$ARGUMENTSMode
design <system>
Design an observability architecture for a service or workflow
review <service or stack>
Audit existing telemetry, dashboards, and alerts
instrument <service or path>
Plan what to emit and where to add instrumentation
alert <service or journey>
Design actionable alerting and escalation
slo <service or journey>
Define SLIs, SLOs, and error budget policy
investigate <signal or symptom>
Structure cross-signal diagnosis for an issue
Natural language about logs, metrics, traces, dashboards, or alertingAuto-detect the closest mode
EmptyShow the mode menu with examples
参数模式
design <system>
为服务或工作流设计可观测性架构
review <service or stack>
审核现有遥测数据、仪表板及告警
instrument <service or path>
规划需要生成的信号及 instrumentation 部署位置
alert <service or journey>
设计可执行的告警与升级策略
slo <service or journey>
定义SLI、SLO及错误预算策略
investigate <signal or symptom>
构建跨信号的问题诊断流程
关于日志、指标、链路追踪、仪表板或告警的自然语言描述自动检测最匹配的模式
无参数显示模式菜单及示例

When to Use

适用场景

  • A team can see failures but cannot explain them quickly
  • Alerts are noisy, late, or missing user-impact context
  • A service lacks clear SLIs, SLOs, or error budget policy
  • You need to add instrumentation to a new service, workflow, or migration
  • Dashboards exist but ownership, escalation, or runbook linkage is weak
  • 团队能够发现故障但无法快速解释原因
  • 告警存在噪音大、延迟或缺少用户影响上下文的问题
  • 服务缺乏明确的SLI、SLO或错误预算策略
  • 需要为新服务、工作流或迁移项目添加 instrumentation
  • 已有仪表板但归属权、升级流程或运行手册关联较弱

Classification Gate

分类指引

  • If the task is active outage coordination, use incident-response-engineer.
  • If the task is CPU, memory, query, or runtime hotspot analysis, use performance-profiler.
  • If the task is AWS-native dashboard, alarm, or log-group setup, use cloudwatch.
  • If the task is CI, deploy, or platform rollout wiring, use devops-engineer.
  • 如果任务是活跃故障协调，请使用incident-response-engineer。
  • 如果任务是CPU、内存、查询或运行时热点分析，请使用performance-profiler。
  • 如果任务是AWS原生仪表板、告警或日志组配置，请使用cloudwatch。
  • 如果任务是CI、部署或平台上线配置，请使用devops-engineer。

Mode Menu

模式菜单

#ModeExample
1Design
design observability for multi-region checkout service
2Review
review telemetry coverage for payments-api
3Instrument
instrument order placement workflow across api and workers
4Alert
alert strategy for login availability and latency
5SLO
slo for customer webhook delivery
6Investigate
investigate rising 5xx with queue lag and timeout traces
序号模式示例
1设计
design observability for multi-region checkout service
2评审
review telemetry coverage for payments-api
3Instrumentation
instrument order placement workflow across api and workers
4告警
alert strategy for login availability and latency
5SLO
slo for customer webhook delivery
6排查
investigate rising 5xx with queue lag and timeout traces

Reference File Index

参考文件索引

FileUse When
references/signal-selection-matrix.md
Choosing between metrics, logs, traces, profiles, and workflow events
references/alert-anti-patterns.md
Reviewing noisy, duplicate, or unactionable alerts
references/sli-slo-examples.md
Defining availability, latency, freshness, or correctness SLIs and SLOs
references/investigation-workflows.md
Structuring symptom-first diagnosis across signals and dependency boundaries
references/output-templates.md
Formatting design, review, instrumentation, alert, SLO, and investigation deliverables
文件适用场景
references/signal-selection-matrix.md
在指标、日志、链路追踪、性能剖析及工作流事件之间进行选择时
references/alert-anti-patterns.md
评审噪音大、重复或不可执行的告警时
references/sli-slo-examples.md
定义可用性、延迟、新鲜度或正确性SLI及SLO时
references/investigation-workflows.md
构建基于症状的跨信号及依赖边界诊断流程时
references/output-templates.md
格式化设计、评审、instrumentation、告警、SLO及排查交付物时

Instructions

操作指南

Mode: Design

模式：设计

  1. Identify the user journeys, critical dependencies, and failure domains that matter most.
  2. Define the questions operators must be able to answer within minutes during degradation.
  3. Read 
    references/signal-selection-matrix.md
    when signal tradeoffs, sampling, or join strategy are unclear.
  4. Choose the minimum useful signals across logs, metrics, and traces for each critical boundary.
  5. Specify correlation identifiers, structured fields, and service naming so signals can be joined reliably.
  6. Define dashboards, alerts, runbook links, and ownership for each critical path.
  7. Call out sampling, retention, and cardinality constraints before recommending implementation details.
  8. Use 
    references/output-templates.md#design-template
    when producing the final deliverable.
  1. 识别最重要的用户旅程、关键依赖及故障域。
  2. 定义在服务降级时运维人员必须能在几分钟内回答的问题。
  3. 当信号权衡、采样或关联策略不明确时，阅读
    references/signal-selection-matrix.md
    。
  4. 为每个关键边界选择日志、指标及链路追踪中最必要的信号。
  5. 指定关联标识符、结构化字段及服务命名，确保信号能可靠关联。
  6. 为每个关键路径定义仪表板、告警、运行手册链接及归属权。
  7. 在推荐实现细节前，明确采样、保留及基数限制。
  8. 生成最终交付物时，使用
    references/output-templates.md#design-template
    。

Mode: Review

模式：评审

  1. Inspect current logs, metrics, traces, dashboards, alerts, and on-call pathways.
  2. Check whether user-visible symptoms can be detected before customer reports arrive.
  3. Read 
    references/alert-anti-patterns.md
    when alert noise, duplication, or escalation quality is part of the review.
  4. Identify blind spots, duplicate signals, noisy alerts, weak labels, and missing trace correlation.
  5. Separate findings into coverage gaps, alert quality issues, and operational debt.
  6. Rank issues by detection risk and operator impact.
  7. Use 
    references/output-templates.md#review-template
    when formatting the audit.
  1. 检查当前的日志、指标、链路追踪、仪表板、告警及值班流程。
  2. 确认是否能在客户反馈前检测到用户可见的症状。
  3. 当评审涉及告警噪音、重复或升级质量时，阅读
    references/alert-anti-patterns.md
    。
  4. 识别盲区、重复信号、噪音告警、弱标签及缺失的链路追踪关联。
  5. 将发现分为覆盖缺口、告警质量问题及运维债务。
  6. 按检测风险及对运维人员的影响对问题排序。
  7. 格式化审核结果时，使用
    references/output-templates.md#review-template
    。

Mode: Instrument

模式：Instrumentation

  1. Map the request or workflow path and identify the decision points, retries, queues, and external calls.
  2. Read 
    references/signal-selection-matrix.md
    before choosing signal types for each boundary.
  3. Define which metrics, logs, and spans should be emitted at each boundary.
  4. Require stable request, tenant, or workflow identifiers only where they aid diagnosis without creating cardinality explosions.
  5. Keep logs structured and redact or exclude secrets and unnecessary PII.
  6. Produce a rollout plan that starts with the highest-value path first.
  7. Use 
    references/output-templates.md#instrumentation-template
    for the emitted deliverable shape.
  1. 映射请求或工作流路径，识别决策点、重试、队列及外部调用。
  2. 为每个边界选择信号类型前，阅读
    references/signal-selection-matrix.md
    。
  3. 定义每个边界应生成的指标、日志及span。
  4. 仅在有助于诊断且不会导致基数爆炸的情况下，要求稳定的请求、租户或工作流标识符。
  5. 保持日志结构化，编辑或排除敏感信息及不必要的PII。
  6. 制定从最高价值路径开始的部署计划。
  7. 生成交付物时，使用
    references/output-templates.md#instrumentation-template
    。

Mode: Alert

模式：告警

  1. Distinguish page-worthy conditions from ticket-only or dashboard-only signals.
  2. Prefer alerts tied to user symptoms, SLO burn, saturation, or stalled workflows over internal noise.
  3. Read 
    references/alert-anti-patterns.md
    before recommending thresholds, paging, or deduplication changes.
  4. Define threshold, duration, owner, runbook, and escalation target for every alert.
  5. Call out what evidence an operator should inspect first after the alert fires.
  6. Reduce duplicate alerts that page different teams for the same symptom.
  7. Use 
    references/output-templates.md#alert-template
    when presenting the alert plan.
  1. 区分需要立即通知的情况与仅需工单或仪表板展示的信号。
  2. 优先选择与用户症状、SLO消耗、资源饱和或停滞工作流相关的告警，而非内部噪音。
  3. 在推荐阈值、通知或去重变更前，阅读
    references/alert-anti-patterns.md
    。
  4. 为每个告警定义阈值、持续时间、负责人、运行手册及升级目标。
  5. 明确告警触发后运维人员应首先检查的证据。
  6. 减少因同一症状通知不同团队的重复告警。
  7. 展示告警计划时，使用
    references/output-templates.md#alert-template
    。

Mode: SLO

模式：SLO

  1. Start from the user-facing promise, not the easiest internal metric to measure.
  2. Read 
    references/sli-slo-examples.md
    when choosing SLI type, exclusions, windows, or error-budget policy.
  3. Define the SLI precisely: numerator, denominator, exclusions, and measurement window.
  4. Choose a target that matches business expectations and operational reality.
  5. State the error budget policy, review cadence, and what actions are triggered when the budget is burned.
  6. Separate availability, latency, freshness, or correctness objectives when one combined SLO would hide tradeoffs.
  7. Use 
    references/output-templates.md#slo-template
    for the final deliverable.
  1. 从面向用户的承诺出发，而非最容易测量的内部指标。
  2. 选择SLI类型、排除项、时间窗口或错误预算策略时，阅读
    references/sli-slo-examples.md
    。
  3. 精确定义SLI：分子、分母、排除项及测量窗口。
  4. 选择符合业务预期及运维实际情况的目标值。
  5. 说明错误预算策略、评审节奏及预算耗尽时触发的行动。
  6. 当合并SLO会掩盖权衡时，分别定义可用性、延迟、新鲜度或正确性目标。
  7. 生成最终交付物时，使用
    references/output-templates.md#slo-template
    。

Mode: Investigate

模式：排查

  1. Start from verified symptoms, not assumed root causes.
  2. Correlate recent deploys, traffic changes, metrics, logs, traces, and dependency health.
  3. Read 
    references/investigation-workflows.md
    when building the hypothesis tree or evidence order.
  4. Build a short hypothesis list and name the next measurement that would confirm or reject each one.
  5. Distinguish signal quality problems from system behavior problems.
  6. If the issue is actively impacting customers and needs command-and-control response, route to incident-response-engineer.
  7. Use 
    references/output-templates.md#investigation-template
    for the final response.
  1. 从已验证的症状出发，而非假设的根本原因。
  2. 关联最近的部署、流量变化、指标、日志、链路追踪及依赖健康状况。
  3. 构建假设树或证据顺序时，阅读
    references/investigation-workflows.md
    。
  4. 构建简短的假设列表，并指出能确认或否定每个假设的下一项测量内容。
  5. 区分信号质量问题与系统行为问题。
  6. 如果问题正在影响客户且需要指挥控制响应，请转至incident-response-engineer。
  7. 生成最终响应时，使用
    references/output-templates.md#investigation-template
    。

Output Requirements

输出要求

  • Every design must name the key questions, signals, owners, and escalation path.
  • Every review must separate missing coverage, alert quality, and observability debt.
  • Every instrumentation plan must define correlation strategy and data-safety constraints.
  • Every alert plan must distinguish paging from informational notifications.
  • Every SLO plan must name the SLI, target, window, and error budget policy.
  • 每个设计必须明确关键问题、信号、负责人及升级路径。
  • 每个评审必须区分覆盖缺口、告警质量及可观测性债务。
  • 每个instrumentation计划必须定义关联策略及数据安全约束。
  • 每个告警计划必须区分通知类告警与信息类通知。
  • 每个SLO计划必须明确SLI、目标值、时间窗口及错误预算策略。

Critical Rules

核心规则

  1. Reject telemetry plans that optimize infrastructure visibility while leaving user-impact questions unanswered.
  2. Require a stable request, workflow, or journey identifier whenever the proposed design needs cross-signal correlation.
  3. Reject labels, fields, or exemplars that create avoidable cardinality explosions or expose raw PII.
  4. Keep dashboards, alerts, and runbooks as separate deliverables; do not collapse them into one artifact or one ownerless checklist.
  5. Page only on symptoms or leading indicators that demand operator action; downgrade the rest to ticket, dashboard, or review-only signals.
  6. Redirect vendor-specific setup, implementation commands, or managed-service configuration to the relevant platform skill instead of inventing provider steps here.
  1. 拒绝优先优化基础设施可见性但未解决用户影响问题的遥测计划。
  2. 当设计需要跨信号关联时，必须要求稳定的请求、工作流或旅程标识符。
  3. 拒绝会导致不必要基数爆炸或暴露原始PII的标签、字段或示例。
  4. 将仪表板、告警及运行手册作为独立交付物；不要将它们合并为单一工件或无归属权的清单。
  5. 仅在症状或前置指标需要运维人员采取行动时触发通知；其余降级为工单、仪表板或仅评审信号。
  6. 将特定厂商的设置、实现命令或托管服务配置转至相关平台技能，而非在此处自行制定提供商步骤。

Scaling Strategy

扩展策略

  • Start with the highest-value user journey or failure path before broadening coverage.
  • Prefer one dependable service-level dashboard and a small alert set over wide but noisy signal sprawl.
  • Expand dimensions, retention, and trace depth only after the base signal set proves useful in practice.
  • 在扩大覆盖范围前，先从最高价值的用户旅程或故障路径开始。
  • 优先选择一个可靠的服务级仪表板及少量告警集，而非广泛但噪音大的信号蔓延。
  • 仅在基础信号集被证明实用后，再扩展维度、保留时间及链路追踪深度。

State Management

状态管理

  • Preserve correlation identifiers across service boundaries, queue hops, and async retries.
  • Track alert ownership, runbook links, and SLO definitions as first-class operational metadata.
  • Re-evaluate telemetry after major architecture, dependency, or traffic-shape changes.
  • 跨服务边界、队列跳转及异步重试保留关联标识符。
  • 将告警归属权、运行手册链接及SLO定义作为一等运维元数据进行跟踪。
  • 在重大架构、依赖或流量形态变更后重新评估遥测系统。

Progressive Disclosure

渐进式披露

  • Do not load all references by default.
  • Read only the reference files needed for the active mode:
    • signal selection work: 
      references/signal-selection-matrix.md
    • alert quality work: 
      references/alert-anti-patterns.md
    • SLI or SLO design: 
      references/sli-slo-examples.md
    • symptom-first diagnosis: 
      references/investigation-workflows.md
    • final formatting: 
      references/output-templates.md
  • Keep 
    SKILL.md
    as the operator contract and use the references for matrices, examples, and output shapes.
  • 默认不加载所有参考文件。
  • 仅读取当前模式所需的参考文件：
    • 信号选择工作：
      references/signal-selection-matrix.md
    • 告警质量工作：
      references/alert-anti-patterns.md
    • SLI或SLO设计：
      references/sli-slo-examples.md
    • 基于症状的诊断：
      references/investigation-workflows.md
    • 最终格式化：
      references/output-templates.md
  • 将
    SKILL.md
    作为运维人员契约，参考文件用于提供矩阵、示例及输出格式。

Scope Boundaries

范围边界

IS for: telemetry design, coverage reviews, instrumentation strategy, SLO definition, alert quality, cross-signal diagnosis.
NOT for: live incident command, low-level profiler output analysis, or vendor-specific configuration walkthroughs.
适用场景： 遥测设计、覆盖范围评审、instrumentation策略、SLO定义、告警质量、跨信号诊断。
不适用场景： 实时事件指挥、低级别剖析器输出分析或特定厂商配置演练。