Distributed Trace Correlation ID Recovery Prompt Template

This prompt is for observability engineers and SRE teams who need to reconstruct broken distributed trace contexts programmatically. The job-to-be-done is generating a precise trace propagation instruction when a service receives a request with a missing, malformed, or truncated traceparent or tracestate header. The ideal user is building an AI-assisted middleware or diagnostic agent that must decide how to inject a new correlation ID, reconcile orphaned spans to a parent, and forward downstream headers without breaking sampling decisions or vendor-specific trace flags. You should use this prompt when your system has partial trace context—such as a valid trace ID but a missing parent span ID—and you need a deterministic recovery plan that a downstream proxy, sidecar, or service mesh can execute.

Do not use this prompt for generating human-readable incident summaries or for root cause analysis of why a trace was broken. It is not designed for log correlation, metric stitching, or alert enrichment. The prompt assumes you already have the raw, broken header fragments and the service's trace configuration (e.g., W3C Trace Context compliance, sampling rates, and vendor flags). It is also inappropriate for systems that do not use distributed tracing or for simple retry logic on HTTP errors—use the API Rate Limit 429 or HTTP 5xx retry playbooks for those cases. The output is a machine-actionable instruction set, not a narrative explanation.

Before using this prompt, ensure you have captured the exact incoming header values, the service's expected trace configuration, and any sampling decision flags that must be preserved. The prompt's value is in its ability to produce a structured recovery instruction that prevents trace fragmentation and maintains end-to-end observability. After generating the instruction, you must validate it against your tracing SDK's header generation logic in a test harness before deploying it to a production middleware path. A malformed recovery can create trace loops or break sampling, so always include a unit test that verifies the output header against a known-good trace context.

This prompt template instructs the model to analyze a broken or incomplete trace context and produce a recovery instruction set. The template is designed to be wired into an observability pipeline where trace propagation has failed—due to header stripping, service mesh misconfiguration, or incomplete context forwarding—and the system needs a structured recovery plan before replaying or continuing the request. The placeholders allow you to inject the specific broken trace state, downstream service requirements, and operational constraints that shape the recovery decision.

textCopy
You are a distributed tracing recovery specialist. Your task is to analyze a broken or incomplete trace context and produce a recovery instruction set that restores trace continuity.

[BROKEN_TRACE_CONTEXT]

[DOWNSTREAM_SERVICE_REQUIREMENTS]

[OPERATIONAL_CONSTRAINTS]

Analyze the broken trace context and produce a recovery plan using the following structure:

1. TRACE DIAGNOSIS
   - Identify which trace fields are missing, malformed, or inconsistent (trace ID, span ID, parent span ID, trace flags, tracestate).
   - Classify the breakage type: missing trace ID, broken parent-child relationship, sampling decision mismatch, or header propagation gap.
   - Note any partial information that can be salvaged.

2. CORRELATION ID INJECTION
   - If the trace ID is missing or invalid, generate a new trace ID following [TRACE_ID_FORMAT] conventions.
   - Preserve any existing correlation IDs from [CORRELATION_ID_SOURCES] if they are valid.
   - Document the relationship between the new trace ID and any business-level correlation IDs (request ID, session ID, transaction ID).

3. SPAN PARENT RECONCILIATION
   - Determine the correct parent span ID based on [UPSTREAM_SERVICE_CONTEXT].
   - If the parent span is unknown, decide whether to create a new root span or link to a synthetic parent.
   - Specify the span kind (CLIENT, SERVER, INTERNAL) for the recovery span.

4. DOWNSTREAM HEADER FORWARDING
   - Produce the exact trace context headers to forward to [DOWNSTREAM_SERVICES].
   - Include traceparent, tracestate, and any vendor-specific headers required by [VENDOR_HEADER_REQUIREMENTS].
   - Preserve the sampling decision from [SAMPLING_DECISION_CONTEXT] or apply the default sampling rule from [SAMPLING_POLICY].

5. RECOVERY VALIDATION CHECKS
   - Verify trace ID format compliance with [TRACE_ID_FORMAT].
   - Confirm parent-child span relationships are acyclic.
   - Validate that sampling flags are consistent across the recovered context.
   - Check that all required downstream headers are present.

6. FALLBACK INSTRUCTIONS
   - If recovery is impossible with available information, specify the escalation path to [ESCALATION_DESTINATION].
   - Include the reason for escalation and what additional information would enable recovery.

Output your response as a JSON object with the following schema:
{
  "diagnosis": {
    "breakage_type": "string",
    "missing_fields": ["string"],
    "salvageable_fields": ["string"],
    "severity": "recoverable|degraded|unrecoverable"
  },
  "recovery_plan": {
    "trace_id": "string",
    "span_id": "string",
    "parent_span_id": "string | null",
    "span_kind": "CLIENT|SERVER|INTERNAL",
    "correlation_ids": {
      "trace_id": "string",
      "request_id": "string | null",
      "session_id": "string | null"
    },
    "downstream_headers": {
      "traceparent": "string",
      "tracestate": "string | null"
    },
    "sampling_decision": "sampled|not_sampled",
    "validation_results": [
      {"check": "string", "passed": true, "detail": "string"}
    ]
  },
  "escalation": {
    "required": true,
    "reason": "string",
    "destination": "string",
    "missing_information": ["string"]
  } | null
}

[CONSTRAINTS]
- Never fabricate trace IDs that could collide with existing traces in [TRACE_ID_NAMESPACE].
- Preserve the original sampling decision unless [SAMPLING_OVERRIDE_POLICY] explicitly permits changes.
- Do not forward headers to services outside [ALLOWED_DOWNSTREAM_SERVICES].
- If the broken context contains PII in custom headers, redact according to [PII_REDACTION_POLICY].

Adaptation guidance: Replace each square-bracket placeholder with the actual data, policies, and constraints from your observability pipeline. The [BROKEN_TRACE_CONTEXT] should contain the raw headers or trace state that failed propagation. The [DOWNSTREAM_SERVICE_REQUIREMENTS] should list the exact header formats and propagation expectations of each downstream service. The [OPERATIONAL_CONSTRAINTS] should capture latency budgets, retry limits, and escalation paths. The output schema is designed to be machine-readable so your harness can parse the recovery plan and apply it programmatically. For high-severity breakage where the model returns "severity": "unrecoverable", route to the escalation path immediately without attempting automated recovery. Validate the output JSON against the schema before applying any header injection—malformed recovery plans can corrupt traces further.

The Distributed Trace Correlation ID Recovery prompt is designed to be called by an observability middleware or sidecar process when a trace context is broken—typically due to a missing traceparent header, a malformed tracestate entry, or a span that has lost its parent reference. The harness should invoke this prompt only after standard W3C Trace Context propagation has failed, not as a primary injection mechanism. The prompt expects structured input containing the partial trace context, the downstream service's expected propagation headers, and the observed breakage point. The output is a corrected set of propagation instructions that the harness must validate before forwarding to the next hop.

Wire the prompt into your request pipeline as a recovery step within an OpenTelemetry SpanProcessor or a custom HTTP middleware. When a span creation fails due to a missing or invalid parent context, serialize the available context—including any partial traceparent, tracestate members, incoming headers, and the target service's expected propagation format—into the [PARTIAL_TRACE_CONTEXT] placeholder. The model will return a JSON object containing a reconstructed traceparent header, a sanitized tracestate list, and a sampling_decision_preserved boolean. Before applying the output, validate that the returned trace-id matches the original if one existed, that the span-id is a valid 16-character hex string, and that the trace-flags byte preserves the sampled bit from the incoming context. If validation fails, increment a trace_recovery_failure metric and fall back to generating a new trace context rather than injecting a malformed one.

Implement a single retry with exponential backoff (1s base, 3s max) if the model call fails or returns unparseable JSON. Do not retry on validation failures—those indicate a semantic error that retrying won't fix. Log every recovery attempt with the original broken context, the model's output, and the validation result to a structured logging sink keyed by the original trace ID (if available) so operators can audit recovery accuracy. For high-throughput services, consider caching recovery decisions by a hash of the partial context input to avoid redundant model calls for identical breakage patterns. Never bypass the sampling decision preservation check: if the model's output flips the sampled flag, discard the recovery and generate a fresh trace context to avoid distorting your tracing sample rate.