Microservices Observability Pattern Review Prompt

This prompt is for a principal engineer, staff architect, or platform SRE who needs to review the observability design across a distributed microservice architecture before a major release, migration, or incident postmortem. The job-to-be-done is not to generate a greenfield design from scratch, but to audit an existing or proposed architecture for systemic blind spots: trace context propagation breaks, inconsistent log correlation, metric naming collisions, and health check gaps that would prevent an on-call engineer from debugging a cross-service failure. Use this prompt when you have a concrete architecture description—a set of service interaction diagrams, a list of services with their telemetry configurations, or a design document—and you need a structured pattern review that flags risks before they become production incidents.

The prompt requires specific input context to be effective. You must provide a description of the service topology, the current or planned observability stack (e.g., OpenTelemetry, Datadog, custom agents), and the known pain points or constraints (e.g., budget limits on log volume, legacy services that cannot be modified). Without this context, the model will produce generic advice that is not actionable. The prompt is designed to produce a review document with categorized findings, severity ratings, and concrete remediation suggestions. It is not a replacement for a full observability audit by a human expert, but it accelerates the initial review and ensures that common failure modes—such as missing trace context in async message queues or inconsistent histogram bucket boundaries—are systematically checked.

Do not use this prompt when you lack a specific architecture to review, when you are looking for a vendor comparison, or when you need a real-time monitoring dashboard configuration. This prompt is for design-time review, not runtime debugging. It is also not suitable for monolithic applications with no service boundaries, as the pattern language assumes distributed system interactions. For high-risk regulated environments (e.g., healthcare data in logs, financial transaction tracing), the output must be treated as an advisory draft that requires human security and compliance review before any remediation is implemented. The prompt includes eval checks that test whether the review output would enable an on-call engineer to trace a request across all services and identify the root cause of a latency spike within a defined time window.

The following prompt template is designed to be copied directly into your AI harness. It expects a description of your microservice architecture, your organization's observability standards, and the specific risk areas you want reviewed. All placeholders are enclosed in square brackets and must be replaced with concrete values before execution. The prompt instructs the model to produce a structured pattern review covering trace context propagation, log correlation, health check consistency, and metric naming standards.

codeCopy
You are an observability architect reviewing a microservice architecture for observability pattern compliance. Your review must be grounded in the provided architecture description and organizational standards. Do not invent services, protocols, or standards that are not present in the input.

## INPUT

### Architecture Description
[ARCHITECTURE_DESCRIPTION]

### Observability Standards
[OBSERVABILITY_STANDARDS]

### Risk Areas to Prioritize
[RISK_AREAS]

### Known Constraints
[CONSTRAINTS]

## OUTPUT SCHEMA

Return a valid JSON object with the following structure:

{
  "review_id": "string",
  "findings": [
    {
      "id": "string",
      "category": "TRACE_PROPAGATION | LOG_CORRELATION | HEALTH_CHECK | METRIC_NAMING | ALERTING | DASHBOARD",
      "severity": "CRITICAL | HIGH | MEDIUM | LOW",
      "service_or_boundary": "string",
      "finding": "string",
      "standard_reference": "string or null",
      "recommendation": "string",
      "distributed_debugging_impact": "string"
    }
  ],
  "cross_cutting_concerns": [
    {
      "concern": "string",
      "affected_services": ["string"],
      "recommendation": "string"
    }
  ],
  "compliance_summary": {
    "trace_propagation_score": "PASS | PARTIAL | FAIL",
    "log_correlation_score": "PASS | PARTIAL | FAIL",
    "health_check_score": "PASS | PARTIAL | FAIL",
    "metric_naming_score": "PASS | PARTIAL | FAIL"
  },
  "distributed_debugging_capability": "FULLY_TRACEABLE | PARTIALLY_TRACEABLE | NOT_TRACEABLE",
  "critical_gaps": ["string"]
}

## CONSTRAINTS

- Only report findings that are supported by the provided architecture description.
- If a standard is not provided for a category, note it as a gap rather than inventing one.
- For each finding, explain the impact on distributed debugging capability.
- Do not recommend specific vendor products unless the standards document explicitly names them.
- If the architecture description is insufficient to evaluate a category, mark that category as "INSUFFICIENT_DATA" in the compliance summary.

To adapt this template, replace each placeholder with concrete content. The [ARCHITECTURE_DESCRIPTION] should include service names, communication protocols, and infrastructure details. The [OBSERVABILITY_STANDARDS] should reference your organization's specific conventions for header propagation, log formats, metric naming, and health check contracts. If you lack formal standards, replace this with a description of current practices and known pain points. The [RISK_AREAS] field focuses the review on the areas that matter most to your team, such as cross-service debugging latency or alert fatigue. The [CONSTRAINTS] field captures deployment limitations like air-gapped environments or legacy services that cannot be modified. After generating the output, validate the JSON structure before passing it to downstream systems. For high-risk production environments, route findings marked CRITICAL to a human architect for review before accepting the recommendations.

This prompt is designed to be integrated into a pre-commit or pull-request review pipeline for architecture decision records (ADRs) or design documents. The primary integration point is a CI/CD check that triggers when a new observability design document is proposed. The application layer should fetch the document content, inject it into the [DESIGN_DOC] placeholder, and send the fully assembled prompt to a capable reasoning model. Because the output is a structured review, the application must parse the model's response and present findings in a review comment or a dedicated dashboard, not just dump raw text into a thread.

For a robust implementation, wrap the model call in a retry loop with a JSON schema validator. The expected output is a JSON object with keys like trace_propagation_assessment, log_correlation_gaps, health_check_issues, and metric_naming_standardization. If the model returns malformed JSON or misses a required key, the harness should retry up to two times with a repair prompt that includes the validation error. Log every attempt, including the raw prompt, the model's response, and the validation result, to an observability platform. This audit trail is critical for debugging prompt drift or model behavior changes over time. For high-risk production systems, add a human approval gate: if the review flags a critical severity finding, the pipeline should block the merge and require an architect to acknowledge the finding before proceeding.

Model choice matters here. Use a model with strong reasoning capabilities and a large context window, as design documents can be lengthy. Avoid lightweight or speed-optimized models that may miss subtle cross-service interaction flaws. Do not use this prompt as a real-time runtime check; it is a design-time review tool. The next step after implementation is to build a regression test suite using golden design documents with known flaws to ensure the prompt continues to catch the right issues after any prompt or model updates.