Distributed Tracing Strategy Prompt Template

This prompt is for architects and SREs who need to produce a concrete, implementable distributed tracing strategy before a single line of instrumentation code is written. Use it when you are designing a new system, overhauling an existing observability stack, or standardizing trace propagation across multiple services and teams. The output is a strategy document that covers sampling decisions, context propagation standards, and span attribute taxonomies, ready for engineering review. The prompt assumes the reader understands distributed systems concepts and OpenTelemetry terminology, and it expects them to supply architectural context including service topology, traffic patterns, and existing observability investments.

Do not use this prompt for debugging a single service or for generating OpenTelemetry configuration files directly; it produces design-level decisions, not config artifacts. It is also inappropriate for teams that have already standardized on a tracing vendor and only need minor tuning. The prompt works best when you have cross-team alignment needs and require a written artifact that multiple engineering teams can review, challenge, and adopt. If you need a quick sampling rate recommendation for one service, a simpler prompt or direct calculation from traffic volume and error budget will serve you better.

Before running this prompt, gather your service topology diagram, current observability toolchain inventory, any regulatory or data residency constraints on telemetry data, and your organization's error budget policies. The prompt will ask you to supply these as [CONTEXT]. After receiving the strategy output, schedule a review with at least one representative from each service team, your SRE lead, and your security engineering contact. The strategy document should be treated as an architecture decision record (ADR) and stored alongside your system design documentation, not buried in an observability vendor's configuration UI.

The following prompt template is designed to produce a comprehensive distributed tracing strategy for a system architecture. It guides the model through the essential decisions: sampling, context propagation, span attribute taxonomies, and instrumentation standards. Use this template as a starting point for an AI-assisted design review, an architecture decision record (ADR) draft, or a self-service tool for platform engineering teams. The square-bracket placeholders are the only parts you need to replace before execution.

textCopy
You are a senior platform architect specializing in observability. Your task is to produce a detailed Distributed Tracing Strategy document for the system described below.

[SYSTEM_ARCHITECTURE_CONTEXT]

Generate a strategy that covers the following sections:
1.  **Objectives and Scope:** What business and technical goals does tracing serve for this system? Which services are in scope?
2.  **Trace Context Propagation Standard:** Specify the exact header format (e.g., W3C Trace Context, B3) and rules for propagation across HTTP, gRPC, and any message queues.
3.  **Sampling Strategy:** Define a head-based sampling policy with rules and rates for different service tiers or request types. Include a tail-based sampling approach for error paths, if applicable.
4.  **Span Attribute Taxonomy:** Define a mandatory set of standard span attributes (e.g., `service.name`, `http.method`, `db.statement`, `user.id`, `error.type`) and naming conventions. Specify cardinality limits for high-cardinality attributes.
5.  **Span Kind and Naming Conventions:** Define rules for naming spans based on operation and kind (SERVER, CLIENT, INTERNAL, etc.).
6.  **Instrumentation Standards:** Recommend libraries (e.g., OpenTelemetry SDKs) and patterns for manual and automatic instrumentation. Address how to handle proprietary or legacy protocols.
7.  **Data Governance and PII:** Define rules for what data must never be added to span attributes (e.g., passwords, full PII). Specify redaction or hashing strategies for sensitive but necessary identifiers.

[CONSTRAINTS]
- The strategy must be vendor-neutral and compatible with the OpenTelemetry standard.
- Prioritize low overhead and minimal performance impact on critical paths.
- The output must be a single, well-structured markdown document.

[OUTPUT_SCHEMA]
{
  "strategy_document": "A complete markdown string containing the tracing strategy.",
  "critical_risks": ["A list of identified risks, such as incomplete propagation paths or high-cardinality attributes that could cause cost overruns."],
  "implementation_phases": ["A phased rollout plan, starting with the most critical services."]
}

To adapt this template, replace the [SYSTEM_ARCHITECTURE_CONTEXT] placeholder with a description of your services, their communication patterns, and your existing observability stack. The [CONSTRAINTS] section is critical for steering the model away from generic advice; specify your organization's standards, such as required libraries or cost limits. The [OUTPUT_SCHEMA] enforces a structured response that can be parsed by downstream tooling, but you can simplify it to a plain text request if you are pasting the result directly into a document. For high-risk production systems, always add a constraint requiring the model to flag any recommendation that could lead to data loss or significant performance degradation.

This prompt is designed to be used as a pre-design review step, not a runtime component. The primary integration point is a documentation or architecture review pipeline where a human architect or SRE provides the [SERVICE_ARCHITECTURE] and [CONSTRAINTS] inputs. The model's output should be treated as a draft strategy document that requires human approval before it becomes the canonical tracing standard for the organization. Do not wire this prompt directly into a CI/CD pipeline that automatically enforces tracing headers or sampling rules without human review, as incorrect propagation standards can silently break distributed traces across services.

For implementation, wrap the prompt in a thin application layer that validates the input and output. Before calling the model, validate that [SERVICE_ARCHITECTURE] contains a list of services, their communication protocols (HTTP, gRPC, message queue), and any existing tracing infrastructure. After receiving the model response, run a structured validation step: parse the output to confirm it includes a context propagation standard (W3C Trace Context or custom headers), a sampling strategy with explicit rates for different traffic classes, and a span attribute taxonomy with at least the required fields for service name, operation, and error status. If any of these sections are missing, trigger a retry with a more constrained [OUTPUT_SCHEMA] that explicitly requires those sections. Log every generation attempt, the validator results, and the final approved version for auditability.

Model choice matters here. Use a model with strong structured reasoning capabilities and a large context window, as the [SERVICE_ARCHITECTURE] input can be lengthy. Claude 3.5 Sonnet or GPT-4o are appropriate for this task. Avoid smaller or faster models that may drop required sections or produce inconsistent sampling rules. If your architecture spans more than 20 services, consider splitting the input into smaller service groups and running the prompt once per group, then merging the results with a synthesis step. For high-compliance environments, store the prompt version, model version, and all input/output pairs in a versioned artifact repository alongside the approved tracing strategy document. The final output should be reviewed by at least one senior engineer who owns the observability stack before it is published as the team's tracing standard.